@acidicsoil/portable-capabilities 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.1.9
+
+### Patch Changes
+
+- [#66](https://github.com/AcidicSoil/portable-capabilities/pull/66) [`ef4277a`](https://github.com/AcidicSoil/portable-capabilities/commit/ef4277a8461419f02873037397c3ea03dc8f17fe) Thanks [@AcidicSoil](https://github.com/AcidicSoil)! - version bump (0.1.9)
+
+## 0.1.8
+
+### Patch Changes
+
+- [#22](https://github.com/AcidicSoil/portable-capabilities/pull/22) [`6dd4920`](https://github.com/AcidicSoil/portable-capabilities/commit/6dd49209a4b7d3ddb87f454312bbc75c5528b85f) Thanks [@AcidicSoil](https://github.com/AcidicSoil)! - Provide a Node `createRequire` bridge in generated ESM CLI bundles so bundled CommonJS code can load Node built-ins without failing at startup.
+
+- [#22](https://github.com/AcidicSoil/portable-capabilities/pull/22) [`6dd4920`](https://github.com/AcidicSoil/portable-capabilities/commit/6dd49209a4b7d3ddb87f454312bbc75c5528b85f) Thanks [@AcidicSoil](https://github.com/AcidicSoil)! - Keep CommonJS-backed runtime dependencies external to the public ESM bundle so the globally installed CLI starts correctly under Node.js.
+
+- [#32](https://github.com/AcidicSoil/portable-capabilities/pull/32) [`c4167b4`](https://github.com/AcidicSoil/portable-capabilities/commit/c4167b408e794ba68d5f153c9846c23b7b57b9ed) Thanks [@AcidicSoil](https://github.com/AcidicSoil)! - Make the CLI source workspace private and keep the repository root as the single npm distribution surface.
+
+- [#22](https://github.com/AcidicSoil/portable-capabilities/pull/22) [`6dd4920`](https://github.com/AcidicSoil/portable-capabilities/commit/6dd49209a4b7d3ddb87f454312bbc75c5528b85f) Thanks [@AcidicSoil](https://github.com/AcidicSoil)! - Publish the `portable-capabilities` executable from the public package, include the canonical assets and runtime schemas in the same tarball, and verify a global-style npm installation end to end.
+
 ## 1.0.0
 
 - Added canonical schemas, contracts, nine shared operations, six families, and 16 analytical roles.

package/README.md

@@ -10,24 +10,19 @@ Define an analytical coding-agent capability once, then generate and install the
 
 Portable Capabilities is a contract-first compiler and CLI. A canonical capability describes its activation criteria, accepted inputs, ordered procedure, output schema, evidence requirements, and allowed effects. The compiler turns that contract into runtime-native skills, commands, agents, workflows, rules, or extensions without maintaining a separate handwritten implementation for every client.
 
-## Review every runtime
+## Review runtime support
 
-Generated packages, one-line installers, and captured native outputs for all seven runtimes are available in [`review/runtime-packages`](review/runtime-packages/README.md).
-
-```bash
-bash review/runtime-packages/codex/install.sh
-```
+Historical generated-package snapshots and captured native outputs for all seven runtimes are available in [`review/runtime-packages`](review/runtime-packages/README.md). Use the typed CLI for current installation; the snapshots do not define the active command surface.
 
 ## Try it
 
-Run one complete example with no configuration:
+Inspect the current command surface:
 
 ```bash
-pnpm demo
+pnpm cli -- --help
+pnpm cli -- runtimes
 ```
 
-This builds the canonical `acceptance-criteria-synthesis` capability for Codex, installs it into a clean project, invokes it through Codex, and writes the result to `.demo/result.md`.
-
 ## What problem does it solve?
 
 Coding-agent clients discover and activate reusable behavior differently. The same capability may require a skill directory in one client, a slash command in another, a subagent definition elsewhere, and different permission metadata in each package.
@@ -72,7 +67,7 @@ Every generated package retains a `SKILL.md` behavioral core plus its required r
 
 ## Runtime packages
 
-The project generates packages for seven clients. Package generation is not the same as authoritative behavioral certification: the runtime profile and retained execution evidence determine whether a client is currently supported, unavailable, unsupported, or covered by an approved exception.
+The project generates packages for seven clients. Package generation is not the same as authoritative behavioral certification: the runtime descriptor and retained execution evidence determine whether a client is currently supported, unavailable, unsupported, or covered by an approved exception.
 
 | Runtime            | Native primitives     | Package and verification guide              |
 | ------------------ | --------------------- | ------------------------------------------- |
@@ -105,63 +100,37 @@ The package installs the executable into npm's configured global binary director
 
 While working from this repository, replace `portable-capabilities` in the examples with `pnpm cli --`.
 
-| Command     | Purpose                                                  |
-| ----------- | -------------------------------------------------------- |
-| `build`     | Compile selected capabilities for selected runtimes      |
-| `validate`  | Validate contracts, projections, resources, and packages |
-| `test`      | Run conformance checks                                   |
-| `diff`      | Detect nondeterministic generated output                 |
-| `inspect`   | Examine a resolved capability and runtime projection     |
-| `invoke`    | Execute a verified package through the CLI boundary      |
-| `install`   | Install all capabilities or an explicit subset           |
-| `status`    | Inspect installation health                              |
-| `upgrade`   | Upgrade installer-owned capability files                 |
-| `downgrade` | Restore an earlier package version                       |
-| `recover`   | Recover an interrupted installation transaction          |
-| `remove`    | Remove installer-owned files safely                      |
+| Command    | Purpose                                      |
+| ---------- | -------------------------------------------- |
+| `wizard`   | Guided capability installation               |
+| `runtimes` | List supported runtime IDs                   |
+| `setup`    | Plan or perform typed setup                  |
+| `install`  | Install one or more capabilities             |
+| `update`   | Update installer-owned capability files      |
+| `status`   | Inspect installation health                  |
+| `remove`   | Remove selected installer-owned files safely |
+| `invoke`   | Execute a verified package through the CLI   |
 
 Machine-readable commands support `--format json`.
 
-## Build, inspect, and install
+## Set up a capability
 
-Set the values for your system manifest, runtime, capability, generated bundle, and clean consumer project:
+Install one or more catalog capabilities into a clean project:
 
 ```bash
-MANIFEST=/path/to/capability-system.yaml
-RUNTIME=codex
-CAPABILITY=<capability-id>
-BUNDLE=/tmp/portable-capabilities-bundle
 CONSUMER=/tmp/portable-capabilities-consumer
-```
-
-Build and inspect one runtime projection:
-
-```bash
-pnpm cli -- build "$MANIFEST" \
-  --target "$RUNTIME" \
-  --role "$CAPABILITY" \
-  --output "$BUNDLE"
-
-pnpm cli -- inspect "$MANIFEST" \
-  --target "$RUNTIME" \
-  --role "$CAPABILITY" \
-  --format json
-```
-
-Install it into a clean consumer project and verify installer health:
-
-```bash
 mkdir -p "$CONSUMER"
-git -C "$CONSUMER" init
-
 pnpm cli -- install \
-  --source "$BUNDLE" \
-  --target "$CONSUMER" \
-  --runtime "$RUNTIME" \
-  --package-version 1.0.0 \
-  --capability "$CAPABILITY"
-
-pnpm cli -- status --target "$CONSUMER" --format json
+  --runtime codex \
+  --capability convention-mining \
+  --project "$CONSUMER" \
+  --approval-policy preapproved
+
+pnpm cli -- status \
+  --runtime codex \
+  --capability convention-mining \
+  --project "$CONSUMER" \
+  --format json
 ```
 
 Then start the selected coding-agent client from `$CONSUMER` and follow its runtime guide. Each guide documents the generated paths, native invocation syntax, user smoke test, maintainer certification procedure, and current evidence status.
@@ -170,9 +139,9 @@ Then start the selected coding-agent client from `$CONSUMER` and follow its runt
 
 Portable Capabilities keeps these claims separate:
 
-1. **Static package validation** proves file layout, schemas, resources, primitive selection, permissions, and integrity metadata.
-2. **Clean installation validation** proves the packed CLI can install, inspect, upgrade, recover, and remove generated packages in a disposable project.
-3. **Native client execution** proves the real client discovered and invoked the generated primitive.
+1. **Static package validation** proves file layout, schemas, resources, and integrity metadata.
+2. **Clean installation validation** proves the packed CLI can install, update, status-check, and remove generated capabilities in a disposable project.
+3. **Native client execution** proves the real client discovered and invoked the generated capability.
 4. **Behavioral conformance** proves the client consumed the operational instructions, produced schema-valid output, preserved evidence requirements, and respected effects.
 
 A static or simulated pass must not be reported as native behavioral support. See [Testing](docs/TESTING.md).

package/dist-release/catalog/schemas/acceptance-criteria-synthesis.output.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://portable-capabilities.dev/schemas/acceptance-criteria-synthesis.output.schema.json",
+  "title": "Acceptance Criteria Synthesis Output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "criteria",
+    "evidenceRequirements",
+    "thresholds",
+    "failureConditions",
+    "coverageMap"
+  ],
+  "properties": {
+    "criteria": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific criteria result with evidence links where material."
+    },
+    "evidenceRequirements": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific evidenceRequirements result with evidence links where material."
+    },
+    "thresholds": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific thresholds result with evidence links where material."
+    },
+    "failureConditions": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific failureConditions result with evidence links where material."
+    },
+    "coverageMap": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific coverageMap result with evidence links where material."
+    }
+  },
+  "x-material-claim-fields": [
+    "criteria",
+    "evidenceRequirements",
+    "thresholds",
+    "failureConditions",
+    "coverageMap"
+  ]
+}

package/dist-release/catalog/schemas/anti-pattern-inversion.output.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://portable-capabilities.dev/schemas/anti-pattern-inversion.output.schema.json",
+  "title": "Anti-Pattern Inversion Output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "antiPatternMap",
+    "positiveRules",
+    "exceptions",
+    "verificationChecks",
+    "coverageEvidence"
+  ],
+  "properties": {
+    "antiPatternMap": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific antiPatternMap result with evidence links where material."
+    },
+    "positiveRules": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific positiveRules result with evidence links where material."
+    },
+    "exceptions": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific exceptions result with evidence links where material."
+    },
+    "verificationChecks": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific verificationChecks result with evidence links where material."
+    },
+    "coverageEvidence": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific coverageEvidence result with evidence links where material."
+    }
+  },
+  "x-material-claim-fields": [
+    "antiPatternMap",
+    "positiveRules",
+    "exceptions",
+    "verificationChecks",
+    "coverageEvidence"
+  ]
+}

package/dist-release/catalog/schemas/behavior-preserving-refactor.output.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://portable-capabilities.dev/schemas/behavior-preserving-refactor.output.schema.json",
+  "title": "Behavior-Preserving Refactor Output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "refactoredArtifact",
+    "changeMap",
+    "equivalenceEvidence",
+    "behavioralDiffs",
+    "rollbackNotes"
+  ],
+  "properties": {
+    "refactoredArtifact": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific refactoredArtifact result with evidence links where material."
+    },
+    "changeMap": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific changeMap result with evidence links where material."
+    },
+    "equivalenceEvidence": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific equivalenceEvidence result with evidence links where material."
+    },
+    "behavioralDiffs": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific behavioralDiffs result with evidence links where material."
+    },
+    "rollbackNotes": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific rollbackNotes result with evidence links where material."
+    }
+  },
+  "x-material-claim-fields": [
+    "refactoredArtifact",
+    "changeMap",
+    "equivalenceEvidence",
+    "behavioralDiffs",
+    "rollbackNotes"
+  ]
+}

package/dist-release/catalog/schemas/canonical-exemplar-generalization.output.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://portable-capabilities.dev/schemas/canonical-exemplar-generalization.output.schema.json",
+  "title": "Canonical Exemplar Generalization Output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "model",
+    "invariants",
+    "variationPoints",
+    "excludedDetails",
+    "coverageEvidence"
+  ],
+  "properties": {
+    "model": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific model result with evidence links where material."
+    },
+    "invariants": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific invariants result with evidence links where material."
+    },
+    "variationPoints": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific variationPoints result with evidence links where material."
+    },
+    "excludedDetails": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific excludedDetails result with evidence links where material."
+    },
+    "coverageEvidence": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific coverageEvidence result with evidence links where material."
+    }
+  },
+  "x-material-claim-fields": [
+    "model",
+    "invariants",
+    "variationPoints",
+    "excludedDetails",
+    "coverageEvidence"
+  ]
+}

package/dist-release/catalog/schemas/constrained-exemplar-adaptation.output.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://portable-capabilities.dev/schemas/constrained-exemplar-adaptation.output.schema.json",
+  "title": "Constrained Exemplar Adaptation Output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "adaptedArtifact",
+    "constraintMapping",
+    "preservedProperties",
+    "deviations",
+    "validationResults"
+  ],
+  "properties": {
+    "adaptedArtifact": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific adaptedArtifact result with evidence links where material."
+    },
+    "constraintMapping": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific constraintMapping result with evidence links where material."
+    },
+    "preservedProperties": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific preservedProperties result with evidence links where material."
+    },
+    "deviations": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific deviations result with evidence links where material."
+    },
+    "validationResults": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific validationResults result with evidence links where material."
+    }
+  },
+  "x-material-claim-fields": [
+    "adaptedArtifact",
+    "constraintMapping",
+    "preservedProperties",
+    "deviations",
+    "validationResults"
+  ]
+}

package/dist-release/catalog/schemas/convention-mining.output.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://portable-capabilities.dev/schemas/convention-mining.output.schema.json",
+  "title": "Convention Mining Output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "conventions",
+    "classification",
+    "supportCounts",
+    "counterexamples",
+    "scope"
+  ],
+  "properties": {
+    "conventions": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific conventions result with evidence links where material."
+    },
+    "classification": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific classification result with evidence links where material."
+    },
+    "supportCounts": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific supportCounts result with evidence links where material."
+    },
+    "counterexamples": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific counterexamples result with evidence links where material."
+    },
+    "scope": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific scope result with evidence links where material."
+    }
+  },
+  "x-material-claim-fields": [
+    "conventions",
+    "classification",
+    "supportCounts",
+    "counterexamples",
+    "scope"
+  ]
+}

package/dist-release/catalog/schemas/conversation-to-specification.output.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://portable-capabilities.dev/schemas/conversation-to-specification.output.schema.json",
+  "title": "Conversation to Specification Output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "requirements",
+    "acceptanceCriteria",
+    "assumptions",
+    "openQuestions",
+    "traceLinks"
+  ],
+  "properties": {
+    "requirements": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific requirements result with evidence links where material."
+    },
+    "acceptanceCriteria": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific acceptanceCriteria result with evidence links where material."
+    },
+    "assumptions": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific assumptions result with evidence links where material."
+    },
+    "openQuestions": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific openQuestions result with evidence links where material."
+    },
+    "traceLinks": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific traceLinks result with evidence links where material."
+    }
+  },
+  "x-material-claim-fields": [
+    "requirements",
+    "acceptanceCriteria",
+    "assumptions",
+    "openQuestions",
+    "traceLinks"
+  ]
+}

package/dist-release/catalog/schemas/delta-analysis.output.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://portable-capabilities.dev/schemas/delta-analysis.output.schema.json",
+  "title": "Delta Analysis Output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "deltas",
+    "materiality",
+    "impactAnalysis",
+    "unchangedAreas",
+    "evidence"
+  ],
+  "properties": {
+    "deltas": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific deltas result with evidence links where material."
+    },
+    "materiality": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific materiality result with evidence links where material."
+    },
+    "impactAnalysis": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific impactAnalysis result with evidence links where material."
+    },
+    "unchangedAreas": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific unchangedAreas result with evidence links where material."
+    },
+    "evidence": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ],
+      "description": "Role-specific evidence result with evidence links where material."
+    }
+  },
+  "x-material-claim-fields": [
+    "deltas",
+    "materiality",
+    "impactAnalysis",
+    "unchangedAreas",
+    "evidence"
+  ]
+}