skillscript-runtime 0.21.1 → 0.22.0

package/dist/skill-dependents.d.ts

@@ -0,0 +1,12 @@
+import type { SkillStore } from "./connectors/types.js";
+/**
+ * Best-effort static reverse-dependency scan: which other stored skills
+ * literally reference `target` via `$ execute_skill(... name="target")` or
+ * `inline(... skill="target")`? Literal-name only — a runtime-resolved
+ * `name="${VAR}"` reference can't be detected statically. Used by the delete
+ * surfaces (CLI `skillfile delete` + the dashboard delete) to warn before
+ * removing a skill other skills compose against. O(N) over the store; runs at
+ * operator-action time, not on a hot path.
+ */
+export declare function findStaticDependents(store: SkillStore, target: string): Promise<string[]>;
+//# sourceMappingURL=skill-dependents.d.ts.map

package/dist/skill-dependents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-dependents.d.ts","sourceRoot":"","sources":["../src/skill-dependents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAc/F"}

package/dist/skill-dependents.js

@@ -0,0 +1,33 @@
+/**
+ * Best-effort static reverse-dependency scan: which other stored skills
+ * literally reference `target` via `$ execute_skill(... name="target")` or
+ * `inline(... skill="target")`? Literal-name only — a runtime-resolved
+ * `name="${VAR}"` reference can't be detected statically. Used by the delete
+ * surfaces (CLI `skillfile delete` + the dashboard delete) to warn before
+ * removing a skill other skills compose against. O(N) over the store; runs at
+ * operator-action time, not on a hot path.
+ */
+export async function findStaticDependents(store, target) {
+    let metas;
+    try {
+        metas = await store.query();
+    }
+    catch {
+        return [];
+    }
+    const esc = target.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const re = new RegExp(`(?:execute_skill\\([^)]*name|inline\\([^)]*skill)\\s*=\\s*"${esc}"`);
+    const dependents = [];
+    for (const m of metas) {
+        if (m.name === target)
+            continue;
+        try {
+            const loaded = await store.load(m.name);
+            if (re.test(loaded.source))
+                dependents.push(m.name);
+        }
+        catch { /* skip unreadable */ }
+    }
+    return dependents.sort();
+}
+//# sourceMappingURL=skill-dependents.js.map

package/dist/skill-dependents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-dependents.js","sourceRoot":"","sources":["../src/skill-dependents.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,KAAiB,EAAE,MAAc;IAC1E,IAAI,KAAK,CAAC;IACV,IAAI,CAAC;QAAC,KAAK,GAAG,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC;IAAC,CAAC;IACzD,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;IAC1D,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,8DAA8D,GAAG,GAAG,CAAC,CAAC;IAC5F,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;YAAE,SAAS;QAChC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACxC,IAAI,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;gBAAE,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACtD,CAAC;QAAC,MAAM,CAAC,CAAC,qBAAqB,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,EAAE,CAAC;AAC3B,CAAC"}

package/docs/adopter-playbook.md

@@ -399,6 +399,21 @@ Turning secured mode on means any skill that's `Approved` without a valid signat
 
 Bundled example skills ship as `# Status: Draft` — a signature baked at package-build time could never validate on your install (the key is per-operator). `skillfile init` locally approves the three seeded demos with *your* machine's authority (secured → provision keypair + sign; unsecured → bare Approved), so they're runnable immediately after init.
 
+## Deleting skills
+
+Deleting a skill is an **operator-only** action — there is **no agent / MCP delete surface** (an agent can author and disable, but only the operator removes). Two surfaces:
+
+| Surface | How |
+|---|---|
+| CLI | `skillfile delete <name>` |
+| Dashboard | the **Delete skill** button on a skill's detail view |
+
+Both are **destructive**: the skill and its version history are erased — there is no trash and no restore in the bundled stores (`FilesystemSkillStore` unlinks the files; `SqliteSkillStore` hard-cascades both tables). Its triggers are dropped from the live scheduler, and its name frees up immediately for a fresh `skill_write`/`store`. The safety is the confirm step plus the reverse-dependency check, not recoverability.
+
+Before deleting, both surfaces run a **best-effort reverse-dependency scan** — which other skills statically reference the target via `$ execute_skill(name="…")` or `inline(skill="…")`. If any do, the delete is **blocked** until you confirm ("`triage-flow` references this — delete anyway?" in the dashboard; `--force` on the CLI). The scan is literal-name only: a runtime-resolved `name="${VAR}"` reference can't be detected statically, so a dynamic caller may slip past the warning — and because delete is permanent, treat the scan as a heads-up, not a guarantee.
+
+Adopter SkillStores implement `delete(name)` per the contract; the runtime only requires "remove from normal views," so a soft-delete (tombstone + filter) is a valid adopter-side choice if you need recovery or audit-grade retention — recovery semantics are the store's concern. See [Connector Contract Reference](connector-contract-reference.md).
+
 ## Shell binary allowlist
 
 **The runtime enforces a default-deny operator allowlist for binaries reachable via `shell(...)` ops.** Skill authors are agents, agents are a weak trust anchor (hallucination, prompt-injection, no human-in-loop at scale), and operator-side scoping converts "a human reviews every skill" from discipline into an enforced constraint at the language level.

package/docs/connector-contract-reference.md

@@ -268,6 +268,8 @@ Adopter substrates with their own ownership concept (e.g., AMP's `author:<id>` t
 
 **`store()` does NOT mint or stamp approval.** In **unsecured** mode a bare `# Status: Approved` is sufficient; the store persists the body verbatim, no token. In **secured** mode, approval is a v3 Ed25519 signature applied by the approve flow (`skillfile approve` / the dashboard), never by `store()`; the MCP `skill_write` handler forces any unsigned `Approved` write to `Draft` before it reaches the store (the bundled stores do the same as defense-in-depth). Your `store()` therefore persists the body as handed to it — it neither stamps nor verifies approval; the runtime owns the gate. See [Adopter Playbook](adopter-playbook.md) §"Approval + secured mode" and `src/approval.ts`.
 
+**`delete()` is destructive in the bundled impls — permanent, name-reclaiming.** The contract signature is `delete(name): Promise<void>`. The bundled stores erase rather than tombstone: `FilesystemSkillStore` unlinks the skill file + version sidecar, `SqliteSkillStore` hard-cascades both tables. After delete the skill is gone from `query()`/`load()`/`metadata()`/`versions()`, the name frees up immediately for a fresh `store()` (clean history, no orphan rows), and there is no trash and no restore. Delete is **operator-only** (CLI `skillfile delete` / the dashboard) — there is no agent/MCP delete surface — and both surfaces gate it behind a confirm + reverse-dependency check. Your impl *may* soft-delete instead (tombstone + filter from normal views); the runtime only requires "remove from normal views," and recovery semantics are your store's concern.
+
 ### DataStore conventions
 
 **`summary`/`detail` split is convention, not contract field.** The DataStore contract gives `write()` a single `content: string`. Bundled `SqliteDataStore` maps this to `summary = first line (≤200 chars)` and `detail = full content`. Adopter substrates with native summary/detail concepts (AMP's `summary` + `detail` columns) can pre-compose and pass via `metadata`, but the basic mapping convention is "first line is the preview." Diverge and the dashboard's memory rendering looks weird, but skills still work.

package/examples/skillscripts/hello-world.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-06-19T12:40:46.559Z",
+  "compiled_at": "2026-06-21T18:48:01.240Z",
   "source_skill": {
     "name": "hello-world"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillscript-runtime",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "Runtime, compiler, lint, CLI, and dashboard for Skillscript — a small declarative language for authoring agent workflows.",
   "license": "MIT",
   "author": "Scott Shwarts <scotts@pobox.com>",
@@ -71,6 +71,8 @@
     "docs/language-reference.md",
     "docs/sqlite-skill-store.md",
     "README.md",
+    "CHANGELOG.md",
+    "UPGRADING.md",
     "LICENSE"
   ],
   "engines": {