@dot-skill/cli 0.4.2 → 0.5.0

package/README.md

@@ -0,0 +1,65 @@
+# `@dot-skill/cli`
+
+CLI implementation for the [Open `.skill` Protocol](https://github.com/dot-skill/dot-skill).
+
+**Public install:** [`skillerr`](https://www.npmjs.com/package/skillerr) · **Bin:** `skill`
+
+Users install `skillerr` (depends on this package). This package is the internal implementation.
+
+## Install (public)
+
+```bash
+npm i -g skillerr
+```
+
+Node ≥ 20. Set `SKILL_HOST` when creating (`cursor`, `ollama`, `claude`, …).
+
+## Quickstart
+
+### Create
+
+```bash
+export SKILL_HOST=cursor
+skill init --title "Demo"
+skill journey --summary "Redacted human+AI work; secrets as refs."
+skill propose --json '[{"title":"Tone","body":"Keep answers short.","type":"decision"}]'
+skill status
+skill checkpoint
+skill compile -m "Demo" --approve --mint
+```
+
+### Ingest / run
+
+```bash
+skill inspect ./file.skill
+skill validate ./file.skill
+skill verify-trust ./file.skill
+skill load ./file.skill
+skill run ./file.skill
+```
+
+### Multi-skill identify
+
+```bash
+skill agent-guide
+skill extract ./journey.json -o ./extraction   # or: skill segment …
+# one workspace per selected candidate → contract-check → compile
+```
+
+```bash
+skill --help
+```
+
+## Related
+
+- [`skillerr`](https://www.npmjs.com/package/skillerr) — public install
+- [`@dot-skill/protocol`](https://www.npmjs.com/package/@dot-skill/protocol)
+- [`@dot-skill/core`](https://www.npmjs.com/package/@dot-skill/core)
+- [`@dot-skill/runtime`](https://www.npmjs.com/package/@dot-skill/runtime)
+- [`@dot-skill/workspace`](https://www.npmjs.com/package/@dot-skill/workspace)
+
+Docs: [Agent](https://github.com/dot-skill/dot-skill/blob/main/docs/AGENT.md) · [Protocol](https://github.com/dot-skill/dot-skill/blob/main/docs/PROTOCOL.md)
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -4,12 +4,14 @@
  *
  * AI agents create; humans review. Continuity drafts for handoff; release for mint.
  *
+ *   npm i -g skillerr                # or: npx -y skillerr --help
  *   export SKILL_HOST=cursor
  *   skill init --title "…"
  *   skill propose --json '[…]'
  *   skill journey --summary "…"
  *   skill checkpoint                 # continuity draft (partial OK)
  *   skill compile -m "…" --mint      # release (complete or refuse)
+ *   skill inspect ./file.skill       # ingest: inspect before run
  *   skill load ./file.skill          # resume handoff in another AI
  */
 export {};

package/dist/cli.js

@@ -4,54 +4,84 @@
  *
  * AI agents create; humans review. Continuity drafts for handoff; release for mint.
  *
+ *   npm i -g skillerr                # or: npx -y skillerr --help
  *   export SKILL_HOST=cursor
  *   skill init --title "…"
  *   skill propose --json '[…]'
  *   skill journey --summary "…"
  *   skill checkpoint                 # continuity draft (partial OK)
  *   skill compile -m "…" --mint      # release (complete or refuse)
+ *   skill inspect ./file.skill       # ingest: inspect before run
  *   skill load ./file.skill          # resume handoff in another AI
  */
-import { readFile, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
-import { inspectSkill, migrateLegacySkill, toSkillMdAdapter, unpackSkill, validatePackageBytes, mintSkillPackage, verifyMintTrust, compileRecipeToSkill, compileSkillSource, approveCompilation, redactSecrets, CompileRefusalError, } from "@dot-skill/core";
+import { readFileSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { inspectSkill, inspectTrustView, migrateLegacySkill, toSkillMdAdapter, unpackSkill, validatePackageBytes, mintSkillPackage, verifyMintTrust, compileRecipeToSkill, compileSkillSource, approveCompilation, redactSecrets, CompileRefusalError, } from "@dot-skill/core";
 import { runSkillArchive } from "@dot-skill/runtime";
 import { lookup, list, verify as registryVerify, publish as registryPublish } from "@dot-skill/registry";
-import { isValidAgentHost } from "@dot-skill/protocol";
+import { agentCreateGuide, assessSkillContract, explainContractAssessment, extractSkillCandidates, formatAgentGuide, isValidAgentHost, scaffoldSkillContract, } from "@dot-skill/protocol";
 import { initWorkspace, requireWorkspace, proposeSection, proposeMany, stage, unstage, status, compileWorkspace, checkpoint, discardSection, loadHead, loadSkillHandoff, setJourney, requireAgentHost, } from "@dot-skill/workspace";
-const VERSION = "0.4.1";
+function loadPackageVersion() {
+    const metadata = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    if (typeof metadata.version !== "string" || metadata.version.length === 0) {
+        throw new Error("Invalid @dot-skill/cli package version metadata");
+    }
+    return metadata.version;
+}
+const VERSION = loadPackageVersion();
 function usage(exitCode = 1) {
     console.log(`skill — Open .skill Protocol CLI v${VERSION}
 
-Skills record declared agent provenance. Humans review, stage, and approve releases.
+Easily create, inspect, and run portable .skill packages.
+Agents create; humans approve releases.
 
-Workspace:
+Create:
   skill init [--title name]
-  skill status                         Completeness checklist + staged sections
-  skill propose --title T --body B     Agent adds a section (requires SKILL_HOST)
+  skill status                         Completeness + staged sections
+  skill propose --title T --body B     Requires SKILL_HOST
   skill propose --json '[...]'
   skill journey --summary "…"          Redacted human+AI journey (no secrets)
   skill add [id...]                    Stage (default: ALL)
   skill unstage [id...] | skill review | skill discard <id>
-  skill checkpoint [-m msg]            Continuity draft for AI handoff (partial OK)
+  skill checkpoint [-m msg]            Continuity handoff (partial OK)
   skill compile -m "msg" [--approve] [--mint] [--profile release|continuity]
-                                       Release compile refuses if incomplete
-  skill load <file.skill>              Resume context in another AI (no private dumps)
-  skill mint [--host name]             Seal release package (AI host required)
+                                       Release refuses if incomplete
+  skill load <file.skill>              Resume continuity in another AI
+  skill mint [--host name]             Seal release (host required)
+
+Multi-skill identify:
+  skill agent-guide [--json]           Exact create/identify protocol steps
+  skill extract <journey.json> [-o dir] [--profile release|continuity]
+                                       Candidate SkillContract/source scaffolds
+  skill segment …                      Alias of extract
 
-Package tools:
-  skill inspect|validate|unpack|run <file.skill>
+Ingest / run:
+  skill inspect <file.skill> [--trust] TrustView (no compile / no model body)
+  skill validate <file.skill>          Structure + hash integrity
+  skill unpack <file.skill>
+  skill verify-trust <file.skill> [--profile minted] [--allow-development-issuer]
+  skill run <file.skill> [--mode execute] [--allow-untrusted]
+                                       Dry-run by default; execute refuses
+                                       unsigned/dev seals without --allow-untrusted
   skill pack <source.json> [-o out.skill] [--approve] [--profile release]
-  skill verify-trust <file.skill> [--profile minted]
-  skill registry list|lookup <digest>  Optional local log (not a public marketplace)
+  skill contract-template              0.5 authoring contract scaffold
+  skill contract-check <contract.json> Completeness + fixes
+  skill registry list|lookup <digest>  Optional local transparency log
 
-Env (agents):
-  SKILL_HOST (required)  SKILL_PROVIDER  SKILL_MODEL  SKILL_DEPLOYMENT
-  SKILL_ENDPOINT  SKILL_ACTOR  SKILL_AGENT_RUNTIME
-  SKILL_INPUT_TOKENS  SKILL_OUTPUT_TOKENS  SKILL_SESSION_ID
+Env:
+  SKILL_HOST (required to create)   SKILL_PROVIDER  SKILL_MODEL
+  SKILL_DEPLOYMENT  SKILL_ENDPOINT  SKILL_ACTOR
+  SKILL_AGENT_RUNTIME  SKILL_AGENT_VERSION  SKILL_SESSION_ID
+  SKILL_AGENT_INVOCATION               Agent runtime marker (anti env-only spoof)
+  SKILL_INPUT_TOKENS  SKILL_OUTPUT_TOKENS
 
-Install: npm i -g @dot-skill/cli   or   npx @dot-skill/cli …
-Why not markdown: docs/WHY.md
+Notes:
+  SKILL_HOST alone never yields verified_issuer trust. Public-dev HMAC is
+  development-only. human/cli/shell/manual hosts are denylisted for mint.
+
+Install:  npm i -g skillerr   →  skill --help
+Docs:     https://github.com/dot-skill/dot-skill
 `);
     process.exit(exitCode);
 }
@@ -73,6 +103,78 @@ async function main() {
         return;
     }
     switch (cmd) {
+        case "agent-guide": {
+            if (flag(rest, "--json")) {
+                console.log(JSON.stringify(agentCreateGuide(), null, 2));
+            }
+            else {
+                console.log(formatAgentGuide());
+            }
+            break;
+        }
+        case "extract":
+        case "segment": {
+            const file = rest.find((a) => !a.startsWith("-"));
+            if (!file) {
+                console.error("Usage: skill extract <journey.json> [-o dir] [--profile release|continuity]\n" +
+                    "       journey.json: { summary, candidates|topics: [...] }\n" +
+                    "       See: skill agent-guide");
+                process.exit(2);
+            }
+            const profile = opt(rest, "--profile") ?? "release";
+            const outDir = opt(rest, "-o") ?? opt(rest, "--out");
+            const raw = JSON.parse(await readFile(resolve(file), "utf8"));
+            const report = extractSkillCandidates(raw, {
+                profile,
+                host: process.env.SKILL_HOST,
+            });
+            if (outDir) {
+                const root = resolve(outDir);
+                await mkdir(root, { recursive: true });
+                await writeFile(join(root, "extraction.json"), `${JSON.stringify(report, null, 2)}\n`);
+                for (const scaffold of report.scaffolds) {
+                    const dir = join(root, "candidates", scaffold.workspace_slug);
+                    await mkdir(dir, { recursive: true });
+                    await writeFile(join(dir, "contract.json"), `${JSON.stringify(scaffold.contract_scaffold, null, 2)}\n`);
+                    await writeFile(join(dir, "source.json"), `${JSON.stringify(scaffold.source_scaffold, null, 2)}\n`);
+                    await writeFile(join(dir, "assessment.json"), `${JSON.stringify({
+                        candidate: scaffold.candidate,
+                        missing: scaffold.missing,
+                        next_steps: scaffold.next_steps,
+                    }, null, 2)}\n`);
+                }
+            }
+            console.log(JSON.stringify({
+                ok: true,
+                written: outDir ? resolve(outDir) : null,
+                ...report,
+                note: "Scaffolds are intentionally incomplete. Complete each SkillContract, one workspace per candidate, then contract-check / status before release compile.",
+            }, null, 2));
+            // Non-zero if any candidate is incomplete (expected for fresh extract).
+            process.exit(report.scaffolds.every((s) => s.candidate.assessment.complete) ? 0 : 2);
+            break;
+        }
+        case "contract-template": {
+            console.log(JSON.stringify(scaffoldSkillContract(), null, 2));
+            break;
+        }
+        case "contract-check": {
+            const file = rest[0];
+            if (!file)
+                usage();
+            const profile = opt(rest, "--profile") ?? "release";
+            const parsed = JSON.parse(await readFile(resolve(file), "utf8"));
+            const contract = parsed && typeof parsed === "object" && "kind" in parsed && parsed.kind === "skill_source"
+                ? parsed.contract
+                : parsed;
+            const assessment = assessSkillContract(contract, profile);
+            console.log(JSON.stringify({
+                assessment,
+                explanation: explainContractAssessment(assessment),
+            }, null, 2));
+            process.exit(assessment.complete ? 0 : 2);
+            break;
+        }
         case "init": {
             const title = opt(rest, "--title");
             const { root, created } = await initWorkspace(process.cwd(), { title });
@@ -216,7 +318,7 @@ async function main() {
         case "compile":
         case "bake": {
             if (cmd === "bake") {
-                console.error("note: `bake` is a Skillerr product term; open protocol command is `skill compile`");
+                console.error("note: `bake` is a legacy alias; the protocol command is `skill compile`");
             }
             const root = requireWorkspace();
             const profile = opt(rest, "--profile") ?? "release";
@@ -230,6 +332,9 @@ async function main() {
                     mint: flag(rest, "--mint"),
                     profile,
                     host: opt(rest, "--host"),
+                    agent_runtime: process.env.SKILL_AGENT_RUNTIME ?? "@dot-skill/cli",
+                    agent_version: process.env.SKILL_AGENT_VERSION ??
+                        (process.env.SKILL_AGENT_RUNTIME ? "unknown" : VERSION),
                     input_tokens: opt(rest, "--input-tokens")
                         ? Number(opt(rest, "--input-tokens"))
                         : undefined,
@@ -298,6 +403,8 @@ async function main() {
                     ? redactSecrets(process.env.SKILL_ENDPOINT)
                     : undefined,
                 agent_runtime: process.env.SKILL_AGENT_RUNTIME ?? "@dot-skill/cli",
+                agent_version: process.env.SKILL_AGENT_VERSION ??
+                    (process.env.SKILL_AGENT_RUNTIME ? "unknown" : VERSION),
             });
             const out = opt(rest, "-o") ?? file;
             await writeFile(resolve(out), packageBytes);
@@ -314,7 +421,7 @@ async function main() {
         case "publish": {
             console.error("Publish is not part of the open .skill happy path.\n" +
                 "Share the .skill file (git, chat, drive). Optional local log: skill registry publish <file>\n" +
-                "Hosted registries are product concerns (e.g. Skillerr), not this protocol.");
+                "Hosted registries are product concerns, not this protocol.");
             process.exit(2);
             break;
         }
@@ -322,7 +429,13 @@ async function main() {
             const file = rest[0];
             if (!file)
                 usage();
-            console.log(JSON.stringify(inspectSkill(new Uint8Array(await readFile(resolve(file)))), null, 2));
+            const bytes = new Uint8Array(await readFile(resolve(file)));
+            if (flag(rest, "--trust")) {
+                console.log(JSON.stringify(inspectTrustView(bytes), null, 2));
+            }
+            else {
+                console.log(JSON.stringify(inspectSkill(bytes), null, 2));
+            }
             break;
         }
         case "validate": {
@@ -409,7 +522,12 @@ async function main() {
                     inputs[k] = v.join("=");
                 }
             }
-            const run = await runSkillArchive(new Uint8Array(await readFile(resolve(file))), { host: process.env.SKILL_HOST ?? "runtime" }, { mode, inputs });
+            const run = await runSkillArchive(new Uint8Array(await readFile(resolve(file))), { host: process.env.SKILL_HOST ?? "runtime" }, {
+                mode,
+                inputs,
+                allow_untrusted: flag(rest, "--allow-untrusted"),
+                allow_development_issuer: flag(rest, "--allow-development-issuer"),
+            });
             console.log(JSON.stringify(run, null, 2));
             process.exit(run.status === "succeeded" || run.status === "paused" ? 0 : 2);
             break;
@@ -419,7 +537,10 @@ async function main() {
             if (!file)
                 usage();
             const profile = (opt(rest, "--profile") ?? "minted");
-            console.log(JSON.stringify(verifyMintTrust(new Uint8Array(await readFile(resolve(file))), profile), null, 2));
+            console.log(JSON.stringify(verifyMintTrust(new Uint8Array(await readFile(resolve(file))), profile, {
+                allow_development_issuer: flag(rest, "--allow-development-issuer"),
+                allow_self_reported: flag(rest, "--allow-self-reported"),
+            }), null, 2));
             break;
         }
         case "registry": {

package/package.json

@@ -1,12 +1,22 @@
 {
   "name": "@dot-skill/cli",
-  "version": "0.4.2",
-  "description": "skill — Open .skill Protocol CLI (continuity and release workflows)",
+  "version": "0.5.0",
+  "description": "CLI implementation for portable .skill packages (install skillerr for the skill bin)",
   "license": "MIT",
   "author": {
     "name": "Bharat Dudeja",
     "url": "https://github.com/bharatdudeja13-cmd"
   },
+  "keywords": [
+    "skill",
+    "skillerr",
+    "dot-skill",
+    ".skill",
+    "ai-agents",
+    "agent-skills",
+    "cli",
+    "protocol"
+  ],
   "type": "module",
   "bin": {
     "skill": "./dist/cli.js",
@@ -21,9 +31,14 @@
     "url": "https://github.com/dot-skill/dot-skill.git",
     "directory": "packages/cli"
   },
+  "homepage": "https://github.com/dot-skill/dot-skill#readme",
+  "bugs": {
+    "url": "https://github.com/dot-skill/dot-skill/issues"
+  },
   "files": [
     "dist/cli.js",
     "dist/cli.d.ts",
+    "README.md",
     "LICENSE"
   ],
   "scripts": {
@@ -32,11 +47,11 @@
     "test": "node --test dist/conformance.test.js"
   },
   "dependencies": {
-    "@dot-skill/core": "^0.4.2",
-    "@dot-skill/protocol": "^0.4.2",
-    "@dot-skill/registry": "^0.4.2",
-    "@dot-skill/runtime": "^0.4.2",
-    "@dot-skill/workspace": "^0.4.2"
+    "@dot-skill/core": "^0.5.0",
+    "@dot-skill/protocol": "^0.5.0",
+    "@dot-skill/registry": "^0.5.0",
+    "@dot-skill/runtime": "^0.5.0",
+    "@dot-skill/workspace": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.21",