@promptframe/cli 0.1.30 → 0.1.32

package/README.md

@@ -4,7 +4,7 @@ PromptFrame component authoring CLI.
 
 Use it to inspect the public component standard, check component folders, validate manifests, inspect the local preview envelope, package source archives, upload components, check build status, rebuild evidence indexes, and rerun layout/security probes.
 
-Current npm registry baseline is `@promptframe/cli@0.1.30`, `@promptframe/contracts@0.1.13`, `@promptframe/component-kit@0.1.11`, and `create-promptframe-component@0.1.17`. The published CLI consumes the contracts AST-aware public security policy evaluator, reports `securityPolicyDigest` / `securityEvaluatorMode` in JSON output, reports `publicResources` for component-level public assets, keeps native `<img>` / `<video>` source checks case-sensitive so Remotion `<Img>` / `<Video>` remain valid, supports endpoint discovery, project list/current diagnostics, self-service CI token create/list/revoke, and packages sanitized lockfile evidence for platform admission.
+Current npm registry baseline is `@promptframe/cli@0.1.32`, `@promptframe/contracts@0.1.13`, `@promptframe/component-kit@0.1.11`, and `create-promptframe-component@0.1.21`. The published CLI consumes the contracts AST-aware public security policy evaluator, reports `securityPolicyDigest` / `securityEvaluatorMode` in JSON output, reports `publicResources` for component-level public assets, keeps native `<img>` / `<video>` source checks case-sensitive so Remotion `<Img>` / `<Video>` remain valid, supports endpoint discovery, project list/current diagnostics, self-service CI token create/list/revoke, single-component and workspace GitHub workflow setup, `promptframe-workspace.json` validation, workspace upload source metadata headers, packages sanitized lockfile evidence for platform admission, and supports `status --fail-on-build-failed` for CI build-status gating.
 
 ```bash
 npm install -D @promptframe/cli
@@ -18,6 +18,9 @@ npx promptframe login --endpoint https://your-promptframe.example/api-proxy
 npx promptframe whoami
 npx promptframe discovery
 npx promptframe project list
+npx promptframe init . --endpoint https://your-promptframe.example/api-proxy
+npx promptframe component create @project-namespace/my-component --display-name "My Component"
+npx promptframe component list
 npx promptframe ci-token create --name "GitHub release" --scope component.upload --scope component.status.read --upload-target marketplace_authoring
 npx promptframe upload ./component.zip --endpoint https://your-promptframe.example/api-proxy
 npx promptframe upload ./component.zip --target project_private_generation --endpoint https://your-promptframe.example/api-proxy
@@ -31,6 +34,7 @@ Endpoint resolution is explicit and public-safe:
 2. `PROMPTFRAME_API_BASE`
 3. `REMOTION_MEDIA_API_BASE`
 4. local config written by `promptframe configure --endpoint <url>`
+5. secret-free `.promptframerc` in the current directory or a parent directory
 
 The CLI embeds no production, Tailscale, local Docker, or private PromptFrame endpoint default. `dev .` starts the component template's local Vite preview shell. `check .` runs the local public policy checks, reports standard freshness for the selected upload lane, and emits deterministic `localReusability` diagnostics so low-reuse marketplace submissions are visible before upload. If no platform endpoint is available, `dev` / `check` return `standard.freshness.offline_degraded` as a warning instead of pretending the online standard was verified. `preview .` reads `src/preview-props.json` and reports the local preview envelope; `preview . --write-local-report` also validates saved `.promptframe/local-previews/*.json` cases and writes `.promptframe/local-previews/preview-report.json` for local author evidence. Neither command runs a custom runtime or replaces the platform iframe preview/render pipeline. Upload success only means the platform accepted the source package for trust-pipeline admission; use `status`, `reindex`, and `probe` to inspect build readiness, evidence/search readiness, and layout/security diagnostics.
 
@@ -38,6 +42,23 @@ Formal platform endpoints use bearer authentication. `promptframe login --endpoi
 
 The platform derives tenant, user, and project from the browser-approved CLI token or scoped CI token. External authors should not hand-enter internal IDs, and formal endpoints reject dev identity headers. `whoami --json` is the safe way to inspect the current token kind, display identity, endpoint, scopes, upload targets, and project binding without exposing the token secret. `discovery --json` reports endpoint capabilities, and `project list --json` / `project current --json` report accessible projects. Server-side project switching is not a public CLI contract yet, so the CLI does not pretend that local config can override the platform principal. CI tokens are project-scoped automation credentials; store them in secret managers such as GitHub Actions secrets, not in source files.
 
+Project context is a source-safe convenience file, not a credential. After login, run:
+
+```bash
+npx promptframe init . --endpoint "$PROMPTFRAME_API_BASE" --json
+```
+
+This writes `.promptframerc` with schema `promptframe-project-context.v0.1.0`, endpoint, tenant/project identifiers, project namespace, default upload target, and workspace config name. It must not contain token secrets, cookies, passwords, API keys, authorization headers, Auth0 subjects, or CI token material. Tokens stay in the local CLI config or CI secret store.
+
+Project components are explicit declarations owned by the platform Project:
+
+```bash
+npx promptframe component create @project-namespace/my-component --display-name "My Component" --json
+npx promptframe component list --json
+```
+
+`component create` and `component list` use bearer auth and do not send owner override fields. CI upload of an undeclared component can fail with `component_registry.not_declared`; create the component first from Admin Project Setup or with `promptframe component create`.
+
 After browser login, authors can create and manage their own project-scoped CI tokens without asking an administrator:
 
 ```bash
@@ -69,19 +90,37 @@ The upload-to-publish lifecycle has multiple gates. `upload` returning success m
 
 The default CLI workflow assumes a single component repository: the current directory is the component package and contains `manifest.json`, `package.json`, `src/`, and optional `public/`.
 
-Monorepos are allowed only when the component path is explicit. `upload <dir|zip>` reads the selected directory or zip package, then derives component identity from that package's `manifest.json`. `PROMPTFRAME_CI_TOKEN` authorizes the upload; it does not map a repository, commit, or tag to a component for you.
+Monorepos are allowed only when component mapping is explicit. `promptframe-workspace.json` is the supported workspace SSOT; it lists each component `id` and relative `path`. `workspace validate` confirms every path exists and every selected directory's `manifest.json` declares the same id before upload. `PROMPTFRAME_CI_TOKEN` authorizes the upload; it does not map a repository, commit, or tag to a component for you.
+
+Create a workspace scaffold:
+
+```bash
+npx -y create-promptframe-component@latest ./component-workspace \
+  --workspace \
+  --component image-particle-remotion \
+  --display-name "Image Particle Remotion"
+cd component-workspace
+npx promptframe workspace validate . --json
+npx promptframe check . --workspace-component @marketplace/image-particle-remotion --json
+npx promptframe setup-ci . --provider github --workspace
+npx promptframe upload . --workspace-component @marketplace/image-particle-remotion --endpoint "$PROMPTFRAME_API_BASE" --json
+```
 
-Safe monorepo examples:
+Add a component to an existing workspace:
 
 ```bash
-npx promptframe check components/motion-intro/image-particle-remotion --json
-npx promptframe upload components/motion-intro/image-particle-remotion --endpoint "$PROMPTFRAME_API_BASE" --json
+npx promptframe workspace add . components/motion-intro/image-particle-remotion --id @marketplace/image-particle-remotion
+npx promptframe workspace validate . --json
+```
 
+The path-explicit single-directory form remains valid if you intentionally run inside one component package:
+
+```bash
 cd components/motion-intro/image-particle-remotion
 npx promptframe upload . --endpoint "$PROMPTFRAME_API_BASE" --json
 ```
 
-Do not run `promptframe upload .` at a monorepo root unless the root itself is a valid component package. If you use tag triggers, treat the tag only as a CI trigger or human-readable version hint; the upload mapping still comes from the CI matrix component path plus the uploaded manifest. A first-class workspace contract with `promptframe-workspace.json`, generated CI matrix support, and manifest/path consistency checks is planned but is not part of the current generated workflow.
+Do not run `promptframe upload .` at a monorepo root unless the root itself is a valid component package. If you use tag triggers, treat the tag only as a CI trigger or human-readable version hint; the upload mapping still comes from `promptframe-workspace.json`, `--workspace-component`, and the uploaded manifest. Workspace uploads send source metadata headers so the platform can record the workspace config, selected component id, component path, and manifest id alongside the build record.
 
 For external CodingAI, the feedback order is: local CLI JSON diagnostics, GitHub Check annotations, Action summary, artifact report, then platform `status` / admission diagnostics. The CLI never needs internal PromptFrame REQ/TASK/QA docs, agent boards, private endpoint defaults, Auth0 subjects, cookies, or token secrets.
 
@@ -96,10 +135,15 @@ npx promptframe upgrade . --dry-run --json
 npx promptframe dev . --dry-run --json
 npx promptframe preview . --json
 npx promptframe preview . --write-local-report --json
+npx promptframe workspace validate . --json
+npx promptframe check . --workspace-component @marketplace/my-component --json
 npx promptframe login --endpoint "$PROMPTFRAME_API_BASE" --json
 npx promptframe whoami --json
 npx promptframe discovery --json
 npx promptframe project list --json
+npx promptframe init . --json
+npx promptframe component list --json
+npx promptframe component create @marketplace/my-component --display-name "My Component" --json
 npx promptframe ci-token list --status active --json
 npx promptframe upload ./component.zip --endpoint "$PROMPTFRAME_API_BASE" --json
 npx promptframe status <buildId> --json
@@ -108,7 +152,7 @@ npx promptframe probe <buildId> --level standard --json
 npx promptframe logout --json
 ```
 
-Every JSON response includes a stable `diagnostic.code`, for example `standard.completed`, `doctor.completed`, `validate.completed`, `check.completed`, `upgrade.dry_run`, `dev.ready`, `preview.ready`, `preview.local_report.written`, `login.completed`, `whoami.completed`, `discovery.completed`, `project.list.completed`, `project.current.completed`, `ci_token.create.completed`, `ci_token.list.completed`, `ci_token.revoke.completed`, `logout.completed`, `upload.completed`, `status.completed`, `reindex.completed`, or `probe.completed`. `standard --json`, `validate --json`, and `check --json` report the active public security policy metadata; use `securityPolicyVersion`, `securityPolicyDigest`, and `securityEvaluatorMode` to compare release cohorts instead of scraping prose. `validate --json` and `check --json` also report `checkedRuleIds` for the public policy checks they ran. `upgrade --dry-run --json` reports package floor changes without writing files. `dev --dry-run --json` reports the local preview command without starting a long-running process. JSON failures include `failureReason` and `retryable`. Missing endpoint failures exit with code `2` and use `<command>.endpoint.missing`; missing credentials use `cli.auth.login_required`.
+Every JSON response includes a stable `diagnostic.code`, for example `standard.completed`, `doctor.completed`, `validate.completed`, `check.completed`, `upgrade.dry_run`, `dev.ready`, `preview.ready`, `preview.local_report.written`, `login.completed`, `whoami.completed`, `discovery.completed`, `project.list.completed`, `project.current.completed`, `project_context.init.completed`, `component.list.completed`, `component.create.completed`, `ci_token.create.completed`, `ci_token.list.completed`, `ci_token.revoke.completed`, `logout.completed`, `upload.completed`, `status.completed`, `reindex.completed`, or `probe.completed`. `standard --json`, `validate --json`, and `check --json` report the active public security policy metadata; use `securityPolicyVersion`, `securityPolicyDigest`, and `securityEvaluatorMode` to compare release cohorts instead of scraping prose. `validate --json` and `check --json` also report `checkedRuleIds` for the public policy checks they ran. `upgrade --dry-run --json` reports package floor changes without writing files. `dev --dry-run --json` reports the local preview command without starting a long-running process. JSON failures include `failureReason` and `retryable`. Missing endpoint failures exit with code `2` and use `<command>.endpoint.missing`; missing credentials use `cli.auth.login_required`.
 
 `standard --json` also returns `authoringStandardRelease` and `freshness`. These fields are the public SSOT for package floors, upload targets, standard source hash, and local freshness decisions: