개발 CLI 명령

pxlab은 화면 대신 터미널에서 명령을 입력해 PipelineXLab 작업을 실행하는 도구입니다. Python SDK와 같은 배포 단위에 담깁니다.

이 문서의 pxlab 명령군은 목표 CLI 계약이며 현재 배포된 실행 파일이 아닙니다. 현재 decorator body나 companion metadata에서 package declaration·executor를 만드는 compiler/build bridge도 아직 없습니다. Component settings schema와 renderer/modal/editor 출력도 계획이며, 다중 선언 container와 host presentation은 Node presentation과 third-party UI의 contract_only V2를 따릅니다. 이 문서에서 verified/signed release는 RFC-005 검증 결과를 기록한 marketplace channel만 뜻합니다.

Project Home, PXFLOW Studio와 Report Workbench 화면만 사용한다면 이 도구는 필요하지 않습니다. 다음 경우에 사용합니다.

이럴 때	쓰는 명령
Function·Component를 담은 package를 만들어 배포할 때	pxlab package init · pxlab package check · pxlab package build · pxlab package publish
Python으로 작성한 Flow를 .pxflow 파일로 저장할 때	pxlab flow materialize
코드로 만든 Flow를 화면에서 확인할 때	pxlab studio open
CI에서 사람 없이 검사만 돌릴 때	pxlab package check --format json
Flow로 만든 사용자 앱을 빌드·배포할 때	pxlab app build · pxlab deploy plan · pxlab deploy request
결과를 읽기 전용으로 게시하거나 웹페이지에 넣을 때	pxlab publication publish · pxlab embed apply

처음 사용하는 개발자는 첫 SDK package 만들기를 먼저 따라 하세요. 이 문서는 그다음에 각 명령이 지켜야 하는 정확한 계약을 확인하는 규격입니다.

CLI는 SDK 문법이나 .pxflow 의미를 별도로 정의하지 않습니다. CLI, Python SDK와 Studio는 같은 declaration materializer, validator와 deterministic writer를 사용합니다.

Report 본문과 Report↔Flow connection은 Python SDK의 px.Report 또는 Report Workbench에서 작성하고 .pxreport에 저장합니다. CLI의 Flow materialize·check·open 명령은 Flow public boundary와 내부 연결을 다루며 Report block, input mapping과 result 위치를 수정하지 않습니다. Python에서 Report를 작성하는 전체 과정은 Python으로 Report와 Flow 함께 만들기에서 확인합니다.

공통 형식

pxlab [--format text|json] [--no-color] <group> <command> [arguments]

• --format text가 terminal 기본값입니다.
• --format json은 stdout에 하나의 JSON document만 출력합니다. 진행 표시와 사람이 읽는 안내를 섞지 않습니다.
• diagnostic은 공통 Diagnostic envelope를 사용합니다.
• path 인자를 생략할 수 있는 명령은 현재 directory를 사용합니다.
• workspace를 변경하는 명령은 --workspace <workspace_key>를 반드시 받습니다. 최근 workspace를 암묵적으로 선택하지 않습니다.
• command line, log와 diagnostic에 access token, secret 값, 내부 UUID mapping과 절대 host path를 출력하지 않습니다.

--format json의 최상위 모양은 다음과 같습니다.

{
  "ok": true,
  "command": "package.check",
  "data": {},
  "diagnostics": []
}

실패하면 ok는 false이고 diagnostics에 하나 이상의 오류가 있습니다. 부분적으로 성공한 것처럼 exit code 0을 반환하지 않습니다.

인증

pxlab auth login

설치·게시·배포처럼 workspace나 catalog를 바꾸는 명령을 쓰기 전에 로그인할 때 사용합니다.

pxlab auth login [--workspace <workspace_key>]

System browser에서 로그인을 완료하고 Local host의 보호된 credential store에 session을 저장합니다. package source, .pxflow, shell history와 환경 파일에 token을 쓰지 않습니다. --workspace를 주면 로그인 뒤 해당 workspace에 접근할 수 있는지도 확인합니다.

검사, local materialize, App build와 Local preview에는 로그인이 필요하지 않습니다. Development install, package publish, Cloud Builder와 Deployment Request처럼 workspace, catalog 또는 실행 환경을 변경하는 명령에는 로그인과 server-side authorization이 필요합니다.

Package 생성

pxlab package init

Function·Component를 담을 새 package 폴더를 처음 만들 때 쓰는 계획된 scaffold 명령입니다.

pxlab package init <directory> --package-key <package_key>

표준 src layout, pyproject.toml, 승인된 entry module과 test directory를 만듭니다.

• directory가 없으면 새로 만듭니다.
• directory가 비어 있지 않으면 아무 파일도 바꾸지 않고 실패합니다.
• Python distribution 이름은 pipelinexlab-<directory 이름>으로 만들며 pyproject.toml에서 배포 전에 바꿀 수 있습니다.
• package_key는 semantic key 문법을 만족해야 합니다.
• 같은 package_key를 기본 public Python module로 만들고 pyproject.toml의 public-module에 명시합니다.
• 같은 정보를 담는 manifest, YAML과 port registry는 만들지 않습니다.

성공 결과에는 생성한 상대 경로와 선택한 packageKey가 들어 있습니다.

설치 package dependency 추가

pxlab dependency add

다른 사람이 공개한 package를 내 package나 Project에서 가져다 쓸 때 쓰는 계획된 dependency 명령입니다.

pxlab dependency add <package_key>@<semver_range> [path]

다른 사용자가 공개한 SDK package를 현재 SDK package 또는 Project dependency에 추가하는 목표 동작입니다. verified marketplace release라면 public Function과 Component export를 함께 설치합니다.

1. 현재 계정의 package 이용 권한과 license를 확인합니다.
2. range를 만족하는 compatible marketplace-verified release, platform, capability와 SBOM 요약을 보여 줍니다.
3. 사용자가 승인하면 [tool.pipelinexlab.dependencies]에 range를 기록합니다.
4. generated dependency lock에 exact package version, platform과 verified release digest를 기록합니다.
5. public Python module, .pyi stub과 executable artifact를 app-private environment에 설치합니다.
6. PXFLOW와 MCP SDK package catalog를 같은 resolved package version과 descriptor digest에서 갱신합니다.

Host의 system Python에 임의로 설치하거나 public package index의 동명 distribution으로 대체하지 않습니다. source에는 사람이 검토할 range를, lock과 materialized Flow에는 verified release에서 resolve한 exact FunctionRef 또는 ComponentRef를 사용합니다.

성공 결과에는 requested range, resolved exact release, public module, 설치된 Function과 Component 목록이 들어 있습니다.

Package 검사

pxlab package check

만든 package를 설치·배포하기 전에 선언이 계약과 맞는지 검사할 때 사용합니다.

pxlab package check [path]

pxlab package check [path] --resolved --project <project_key>

계획된 기본 명령은 승인된 entry module에서 @px.function, @px.component, 계획된 record decorator, flow = px.Flow(...), flow.input(...), flow.node(...), flow.connect(...), flow.result(...), flow.group(...), flow.subflow(...), @px.app과 설치한 Component package가 제공한 optional decorator를 검사합니다. Group membership, public Function/Component/type, generated .pyi, FunctionDescriptor·ComponentDescriptor, 계획된 setting schema와 verified presentation이 일치해야 합니다. @px.app은 standalone App Surface 계약을 검사합니다.

설치한 Component package가 Extension으로 template·editor·manual contribution을 추가하면 해당 marketplace-verified Extension checker를 함께 실행합니다. --resolved는 exact package dependency와 ComponentRef까지 확인합니다.

dependency lock·Extension editor 검사는 각각 별도 versioned dependency 계약과 RFC-014가 승인된 package generation에만 적용합니다. 현재 node-presentation V2 범위는 component-declared-settings@1 선언, 빈 Python dependency 목록, declaration JSON과 참조된 Python source만 허용하는 closed container이며, rich editor는 RFC-016의 component-rich-surface-declaration@1이 소유합니다.

이 명령은 Function/Component body의 업무 계산을 실행하지 않습니다. import-time side effect, 동적 registry와 임의 module scan에 의존하는 package는 거부합니다. 모든 exact dependency와 Node placement target을 resolve해 missing package/component, version·contract mismatch와 catalog/access failure evidence를 남깁니다. saved exact ComponentRef, raw settings와 usage-derived partial ports만 있는 unresolved Component를 성공으로 처리하지 않으며 full/last-verified contract snapshot을 가정하지 않습니다.

성공 결과에는 다음 값이 들어 있습니다.

{
  "checkLevel": "resolved",
  "packageKey": "structural_checks",
  "packageVersion": "0.1.0",
  "publicModule": "structural_checks",
  "functions": ["girder_utilization@1.0.0"],
  "components": [
    {
      "componentKey": "model_viewer",
      "descriptorDigest": "sha256:..."
    }
  ],
  "flows": ["girder_review"],
  "appSurfaces": ["bearing_check"],
  "manuals": ["ko/index", "en/index"],
  "missingPackEvidence": [],
  "descriptorDigest": "sha256:...",
  "diagnostics": []
}

checkLevel은 declaration 또는 resolved입니다. components는 exported componentKey와 descriptor 검증 요약입니다. settings 선언은 component-declared-settings@1이, 그 값 판정은 저장 시점의 Flow change tier가, host presentation은 별도 resolution 계약이 소유하므로 이 결과에 setting/presentation 검증을 넣지 않습니다. 이전 목표 예제의 presentation.kind와 contractDerived spelling은 compatibility audit에서만 추적하며 새 결과 member로 발행하지 않습니다. missingPackEvidence는 legacy/internal serialized field 이름이며 exact package/version 상태와 safe diagnostic code만 담습니다. Component package가 optional contribution inventory를 제공하면 package namespace 아래의 Extension summary에 schema digest가 포함됩니다.

검사 오류가 있으면 build, development install과 publish를 진행할 수 없습니다.

Flow 저장

pxlab flow materialize

코드로 작성한 Flow 하나를 .pxflow 파일로 저장할 때 사용합니다.

pxlab flow materialize [path] --flow <flow_key> --output <file.pxflow>

SDK declaration의 Flow 하나를 direct .pxflow로 저장합니다.

• --flow는 entry module 안의 exact flowKey입니다.
• output 확장자는 .pxflow여야 합니다.
• output parent directory가 없으면 만듭니다.
• 기존 파일의 bytes가 같으면 성공으로 처리합니다. 기존 파일이 다르면 덮어쓰지 않고 PX_OUTPUT_EXISTS를 반환하므로 사용자가 기존 파일을 검토하거나 다른 output을 선택해야 합니다.
• 어느 Node target body도 실행하지 않고 Flow wiring, exact target ref, raw Component settings, input binding·public result usage에서 유도한 partial ports와 same-Flow Group membership만 materialize합니다. full/last-verified Component contract snapshot은 저장하지 않습니다.
• manifest, YAML과 compatibility mirror를 만들지 않습니다.

성공 결과에는 output 상대 경로, flowKey, semantic digest와 execution digest가 들어 있습니다.

Studio에서 열기

pxlab studio open

코드로 작성한 Flow를 PXFLOW Studio 화면에서 확인할 때 사용합니다.

pxlab studio open [path] --flow <flow_key>

같은 SDK declaration을 SDK-linked 상태로 PXFLOW Studio에서 엽니다. 설치된 Local 앱이 있으면 현재 사용자 session으로 전달하고, Local 앱이 없으면 로그인한 Cloud workspace에서 열 수 있는 주소를 안내합니다.

명령이 source를 .pxflow 사본으로 바꾸거나 source owner를 변경하지 않습니다. Studio에서 지원되는 수정은 source diff와 영향을 먼저 보여 주며, Apply 후 rematerialize 결과가 같을 때만 source에 반영합니다.

Component template을 화면에서 확인하려면 해당 Component를 배치한 Flow를 Studio에서 열고 Node를 더블클릭합니다. Template source 변경은 source-safe diff로, 현재 Node draft는 Flow revision의 Node setting으로 저장합니다.

Report에서 이 Flow를 연결하려면 Report Workbench에서 Flow public input/result를 선택합니다. 이 연결은 .pxreport revision으로 저장됩니다.

PXFLOW App Builder

pxlab app open

코드로 선언한 App을 App Builder 화면에서 열 때 사용합니다.

pxlab app open [path] --app <surface_key>

@px.app 또는 .pxflow.appSurfaces의 exact PXFLOW App을 Builder에서 엽니다. Local 앱이 설치되어 있으면 현재 사용자 session으로 전달하고, 없으면 로그인한 Cloud Workspace에서 열 수 있는 주소를 안내합니다.

SDK-linked App의 Builder 변경은 source diff와 영향을 먼저 보여 줍니다. Apply 후 rematerialize 결과가 같은 direct App Surface definition과 일치해야 하며, source로 안전하게 표현할 수 없으면 PXFLOW-native 사본을 만들지 묻습니다.

pxlab app check

App을 미리 보거나 빌드하기 전에 화면 구성과 참조가 맞는지 검사할 때 사용합니다.

pxlab app check [path] --app <surface_key>

다음을 검사하며 Flow를 실행하거나 file을 변경하지 않습니다.

• exact surfaceKey, target flowKey와 unique pageKey
• generated Flow input/result reference와 connection=True
• port direction, required input과 result projection
• pxflow_app format contract와 responsive layout
• 필요한 signed SDK package release, Function/Component descriptor, Component setting/presentation, App Surface driver와 asset closure
• accessibility, secret·path 금지와 deployment portability

pxlab app preview

배포하지 않고 내 컴퓨터에서 App 화면을 확인할 때 사용합니다.

pxlab app preview [path] --app <surface_key>

Local preview session을 열며 Cloud resource나 공개 route를 만들지 않습니다. Preview 화면에서 사용자가 Test run을 명시적으로 선택하기 전에는 Flow를 실행하지 않습니다.

pxlab app build

배포에 사용할 App 후보를 만들 때 사용합니다.

pxlab app build [path] --app <surface_key> --output <candidate_directory>

App Surface direct object, exact Flow revision, signed SDK package release·dependency lock, Function/Component descriptor, Component setting/presentation, format driver, asset inventory, SBOM과 validation evidence를 포함하는 immutable App Candidate를 만듭니다. current workspace path, editor session과 mutable head는 candidate identity가 아닙니다.

같은 source closure와 toolchain은 같은 candidate digest를 만들어야 합니다. output directory의 generated file을 수정하면 deployment plan이 거부됩니다.

PXFLOW App 배포

pxlab deploy plan

배포하기 전에 대상 workspace·환경·접근 범위와 차단 사유를 미리 확인할 때 사용합니다.

pxlab deploy plan <candidate_directory>
  --workspace <workspace_key>
  --environment <development|production>
  --access <public|unlisted|authenticated>

Candidate와 대상 Workspace·environment·접근 정책을 결합해 읽기 전용 Deployment Plan을 만듭니다. exact dependency closure, 예상 resource, URL·slug 충돌, entitlement, secret requirement, policy와 차단 사유를 반환하지만 App을 활성화하지 않습니다.

Plan은 planRef, 짧은 유효 기간과 planDigest를 가집니다. source, candidate, target policy 또는 권한 조건이 바뀌면 기존 Plan으로 request할 수 없습니다.

pxlab deploy request

검토한 Plan대로 App을 실제로 활성화할 때 사용합니다.

pxlab deploy request <plan_ref>
  --confirm-digest sha256:<reviewed_plan_digest>

검토한 Plan을 실행 환경에 활성화하도록 비동기 요청합니다. interactive terminal은 exact 영향과 digest를 보여 준 뒤 사용자 확인을 요구합니다. Automation identity도 제한된 deployment 권한과 미리 검토한 digest가 필요하며 --confirm-digest가 authorization, license, quota 또는 policy를 우회하지 않습니다.

성공 결과는 deploymentRequestRef와 초기 상태를 반환합니다. route가 준비되기 전에 성공한 것처럼 URL을 반환하지 않습니다.

상태와 lifecycle 명령

배포 진행 상태를 확인하거나 배포를 내리고 이전 revision으로 되돌릴 때 사용합니다.

pxlab deploy status <deployment_request_ref>
pxlab deploy cancel <deployment_request_ref>
pxlab deploy withdraw \
  --workspace <workspace_key> --project <project_key> --flow <flow_key> \
  --app <surface_key> --environment <environment_key>
pxlab deploy retire-revision \
  --workspace <workspace_key> --project <project_key> --flow <flow_key> \
  --app <surface_key> --environment <environment_key> --revision <number>
pxlab deploy rollback \
  --workspace <workspace_key> --project <project_key> --flow <flow_key> \
  --app <surface_key> --environment <environment_key> --to-revision <number>

• status는 requested | admitted | provisioning | verifying | active | rejected | failed | cancelled | indeterminate 중 현재 상태와 안전한 diagnostic을 반환합니다.
• cancel은 아직 terminal이 아닌 request의 후속 작업을 중단합니다.
• withdraw는 현재 App Deployment를 내리되 immutable revision과 audit를 삭제하지 않습니다. 영향받는 App Embed를 함께 보여 주고 같은 승인에서 suspend 또는 withdraw하지 않으면 거부합니다.
• retire-revision은 exact 표시 revision을 더 이상 servable하지 않게 합니다. active/suspended/expired Embed가 참조하면 새 target promotion 또는 delivery withdraw를 같은 Plan에서 해결해야 합니다. Suspend만으로는 reference가 남으므로 retire할 수 없습니다.
• rollback은 기존 revision을 수정하지 않고 선택한 표시 revision의 candidate를 가리키는 새 Deployment Request를 만듭니다.
• 모든 lifecycle 명령은 server에서 actor, Workspace, license, expected generation과 target 상태를 다시 확인합니다.

읽기 전용 Publication

Publication은 항상 읽기 전용입니다. 실행 가능한 외부 화면은 이 명령이 아니라 앞 절의 App Deployment를 사용합니다.

pxlab publication plan

Flow 결과를 읽기 전용으로 공개하기 전에 공개 범위와 영향을 확인할 때 사용합니다.

pxlab publication plan
  --workspace <workspace_key>
  --project <project_key>
  --flow <flow_key>
  --publication-key <publication_key>
  --audience <workspace|unlisted|public>

현재 managed Flow head를 읽고 exact immutable revision, public-safe dependency/result/evidence closure, license, permission과 audience 영향을 보여 주는 Plan을 만듭니다. 기존 publicationKey를 주면 새 version plan이며 현재 active version과 차이를 함께 반환합니다.

Local 외부 .pxflow는 자동 업로드하지 않습니다. 사용자가 Cloud/server Workspace에 고정 사본을 올리고 inclusion preview를 승인한 뒤 다시 실행하도록 안내합니다.

pxlab publication publish

검토한 Plan대로 새 공개 version을 올릴 때 사용합니다.

pxlab publication publish <plan_ref>
  --confirm-digest sha256:<reviewed_plan_digest>

새 immutable Publication Version을 만든 뒤 모든 검증이 성공한 경우에만 active version을 원자적으로 전환합니다. 실패하면 기존 active version을 유지합니다.

Publication 상태와 lifecycle

공개 상태를 확인하거나 공개 범위를 바꾸고 중단·철회할 때 사용합니다.

pxlab publication status <publication_key>
pxlab publication versions <publication_key>
pxlab publication update-policy <publication_key> --audience <workspace|unlisted|public>
pxlab publication suspend <publication_key>
pxlab publication resume <publication_key>
pxlab publication withdraw <publication_key>

status와 versions는 읽기 전용 query입니다. update-policy, suspend, resume과 withdraw는 current generation, 영향 preview와 명시적 승인을 요구합니다. update-policy는 immutable version을 다시 쓰지 않고 현재 closure를 새 audience에서 재검사합니다. withdraw 뒤 같은 record를 되살리지 않으며 새 게시가 필요하면 새 Publication을 만듭니다.

HTML EmbedDelivery

pxlab embed plan

게시한 결과나 App을 외부 웹페이지에 넣기 전에 대상과 허용 도메인을 정할 때 사용합니다.

읽기 전용 Viewer target:

pxlab embed plan
  --workspace <workspace_key>
  --embed-key <embed_key>
  --publication <publication_key>
  --version <publication_version>
  --access <public|unlisted|authenticated>
  --origin <https_origin>...

실행 가능한 App target:

pxlab embed plan
  --workspace <workspace_key>
  --project <project_key>
  --flow <flow_key>
  --embed-key <embed_key>
  --app <surface_key>
  --environment <environment_key>
  --access <public|unlisted|authenticated>
  --origin <https_origin>...

--publication과 --app은 함께 사용할 수 없습니다. Publication target은 exact version을 pin합니다. App target은 workspace + project + flow + app + environment에서 현재 Active Deployment Revision을 resolve해 Plan에 pin합니다. App target에는 하나 이상의 exact HTTPS --origin이 필수입니다. 빈 origin을 any-site로 해석하지 않습니다.

기존 embedKey를 주면 target promotion 또는 policy update plan을 만듭니다. Publication target과 App target 사이의 kind 변경은 허용하지 않으며 기존 EmbedDelivery를 withdraw한 뒤 새 key를 사용해야 합니다.

pxlab embed apply

검토한 Plan대로 Embed를 만들거나 대상을 바꿀 때 사용합니다.

pxlab embed apply <plan_ref>
  --confirm-digest sha256:<reviewed_plan_digest>

Plan이 고정한 operation에 따라 embed.create, embed.promote_target 또는 embed.update_policy를 호출합니다. CLI가 generic JSON patch나 별도 manifest를 만들지 않습니다.

Embed 상태와 snippet

삽입용 HTML을 받거나 Embed를 중단·철회할 때 사용합니다.

pxlab embed status <embed_key>
pxlab embed snippet <embed_key>
pxlab embed suspend <embed_key>
pxlab embed resume <embed_key>
pxlab embed withdraw <embed_key>

snippet은 current generation에 맞는 iframe HTML과 top-level fallback URL을 반환합니다. management token, account credential, 내부 UUID와 source path를 출력하지 않습니다. lifecycle 변경은 expected generation과 명시적 승인을 요구합니다.

정확한 target, origin, lifecycle과 diagnostic은 게시·Embed 전달 계약을 따릅니다.

Development catalog 등록

이 절의 catalog는 Function, Component와 Extension을 같은 release로 제공하는 SDK package catalog입니다. Flow·Project template과 Component package가 제공하는 template을 배포하는 Template Marketplace는 별도 저장소와 권한 체계를 사용합니다. pxlab package install|publish는 template listing, 가격, 구매 권리 또는 Organization allocation을 만들지 않습니다. template의 release·listing·권리 계약은 Template Marketplace·Organization Library를 따릅니다.

pxlab package install

아직 배포하지 않은 개발 중 package를 workspace에서 먼저 시험 사용할 때 쓰는 목표 동작입니다.

pxlab package install <path> --workspace <workspace_key> --development

현재 source revision을 지정한 workspace의 개발 catalog에 등록합니다. PXFLOW의 Component·Function 목록과 MCP search에서 개발 상태임을 표시하며 stable release와 섞지 않습니다.

명령은 다음 순서로 동작합니다.

1. package check와 같은 검사를 수행합니다.
2. 로그인과 workspace write 권한을 확인합니다.
3. package, Function/Component, setting/presentation과 capability 변경 내용을 보여 줍니다.
4. 사용자가 승인하면 immutable development revision을 등록합니다.

같은 source digest를 다시 등록하면 새 revision을 만들지 않고 기존 결과를 반환합니다.

Release candidate 만들기

pxlab package build

catalog에 올릴 release 후보를 만들 때 쓰는 목표 동작입니다.

pxlab package build [path] --output <directory>

재현 가능한 release candidate를 만듭니다. Candidate에는 wheel, FunctionDescriptor·ComponentDescriptor, Component/setting inventory, optional presentation bytes, public SDK facade와 .pyi type stub, normalized dependency lock, missing-dependency resolution evidence, 선택적인 Extension bundle·App Surface descriptor와 format module·package manual, SBOM과 각 파일 digest가 포함됩니다. Registry signature는 publish 검증 뒤 발급합니다.

이 목록은 여러 후속 package generation을 합친 목표 build입니다. node-presentation V2 candidate는 setting inventory·non-empty dependency lock·presentation bytes·Extension editor bundle을 포함하지 않으며, 해당 산출물은 각 versioned 후속 계약과 RFC-014 승인을 받은 뒤에만 추가합니다.

• source tree가 dirty여도 build는 가능하지만 provenance에 dirty 상태를 기록하고 stable publish를 차단합니다.
• 같은 source, lock, toolchain과 platform에서 같은 package bytes와 digest가 나와야 합니다.
• output directory 안의 generated metadata를 수정하면 publish 검증이 실패합니다.
• build가 업무 계산을 실행하지 않습니다. test는 개발자가 별도 test command로 수행하고 그 결과를 release evidence에 연결합니다.

성공 결과에는 candidate directory, package byte digest, descriptor digest, dependency lock digest와 SBOM digest가 들어 있습니다.

Catalog에 배포

pxlab package publish

만든 release 후보를 catalog에 올려 다른 사용자가 설치할 수 있게 할 때 사용합니다.

pxlab package publish <candidate_directory> --channel <development|stable>

Release candidate를 catalog에 올립니다. 명령은 Function version, Component contract/setting/presentation 변화, 호환성, capability, missing-dependency evidence, 지원 Runtime, test와 공급망 검사 결과를 먼저 보여 줍니다. Interactive terminal에서는 사용자가 승인한 뒤 업로드합니다.

자동화 환경은 미리 검토한 candidate digest를 다음처럼 고정해야 합니다.

pxlab package publish dist/release \
  --channel stable \
  --confirm-digest sha256:<reviewed_candidate_digest>

Automation identity에도 별도의 publish 권한이 필요합니다. --confirm-digest는 권한이나 policy 검사를 우회하지 않습니다.

Registry는 package bytes, Function/Component descriptor와 optional presentation, dependency lock, SBOM, publisher와 channel policy를 검증한 뒤 Signed SDK package release envelope를 발급합니다. 같은 release envelope가 Function과 Component export를 함께 pin하며 일부 검사만 통과한 package를 공개하지 않습니다.

명령과 저장 변경 범위

명령	Local file 변경	Workspace 변경	사용자 승인
auth login	보호된 credential store만 변경	session 생성	browser 로그인
package init	새 source tree 생성	없음	명령 자체가 요청
dependency add	dependency range와 generated lock 변경, app-private environment 갱신	package entitlement 조회	release·license·capability preview 후 필요
package check	없음	없음	필요 없음
flow materialize	지정한 .pxflow 작성	없음	명령 자체가 요청이며 다른 기존 파일은 덮어쓰지 않음
studio open	없음	열린 session만 생성	필요 없음
app open	없음	Local 또는 Cloud Builder session만 생성	Cloud session이 필요하면 browser 로그인
app check	없음	없음	필요 없음
app preview	없음	Local preview session만 생성	실제 Test run은 별도 승인 규칙 사용
app build	candidate directory 생성	없음	명령 자체가 요청
deploy plan	없음	짧은 수명의 읽기 전용 Plan 생성	필요 없음; 로그인·권한 검사는 수행
deploy request	없음	비동기 Deployment Request 생성	interactive 승인 또는 exact plan digest 필요
deploy cancel|withdraw|retire-revision|rollback	없음	deployment 또는 exact revision lifecycle 변경	영향받는 Embed preview와 명시적 승인 필요
publication plan|status|versions	없음	읽기 전용 Plan/query만 생성	변경 승인 없음
publication publish	없음	immutable Publication Version 생성·활성화	interactive 승인 또는 exact plan digest 필요
publication update-policy	없음	stable Publication audience 변경	영향 preview와 명시적 승인 필요
publication suspend|resume|withdraw	없음	Publication lifecycle 변경	영향 preview와 명시적 승인 필요
embed plan|status|snippet	없음	읽기 전용 Plan/query만 생성	변경 승인 없음
embed apply	없음	EmbedDelivery 생성·target/policy 변경	interactive 승인 또는 exact plan digest 필요
embed suspend|resume|withdraw	없음	EmbedDelivery lifecycle 변경	영향 preview와 명시적 승인 필요
package install --development	없음	development revision 생성	변경 preview 후 필요
package build	candidate directory 생성	없음	명령 자체가 요청
package publish	없음	catalog release 생성	interactive 승인 또는 exact digest 필요

Canonical release workspace

Wheel과 generated binding re-pin의 canonical workspace는 /home/resethome/projects/PipelineXlab/pipelineXlab_pxflow 입니다. 다른 경로에서의 wheel re-pin은 V1에서 unavailable이며 named refusal은 non-canonical-workspace-repin입니다.

구현 불변식

• CLI가 Python용 별도 schema owner가 되지 않습니다.
• Native CLI, Python SDK binding, Studio WASM과 server validator가 같은 valid/invalid fixture, digest와 diagnostic code/path를 반환합니다.
• path, label, UUID, source line과 호출 순서로 semantic key를 만들지 않습니다.
• build, materialize와 check가 Function/Component body나 PXFLOW를 실행해 결과를 추측하지 않습니다. 필요한 declaration builder 평가는 권한 없는 deterministic authoring sandbox에 한정합니다.
• workspace 변경 명령은 현재 revision과 권한을 server에서 다시 확인합니다.
• stdout JSON은 안정된 공개 결과이며 progress log, ANSI code와 raw exception을 섞지 않습니다.
• network 오류나 중단 뒤 같은 digest를 재전송해도 중복 development revision이나 release를 만들지 않습니다.
• Builder와 CLI는 같은 App Candidate, Deployment Plan·Request application command를 사용합니다. CLI가 workspace absolute path를 서버에 보내 즉시 ZIP publish하는 별도 경로를 만들지 않습니다.
• package publish, Publication과 Deployment Request는 서로 다른 command, capability와 lifecycle을 사용합니다.
• Publication은 읽기 전용이며 App 실행을 위해 runnable variant를 만들지 않습니다. Embed target이 Publication Version이면 Viewer, Deployment Revision이면 App으로 결정합니다.
• Publication/Embed CLI가 .pxflow, SDK source, YAML 또는 sidecar manifest에 URL, token, origin과 lifecycle을 쓰지 않습니다.