@hasna/skills 0.9.2 → 0.9.4

package/bin/mcp.js

@@ -20019,7 +20019,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.9.2",
+    version: "0.9.4",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -20028,6 +20028,7 @@ var init_package = __esm(() => {
       "skills-serve": "bin/server.js",
       "skills-server": "bin/server.js",
       "skills-worker": "bin/worker.js",
+      "skills-maintenance": "bin/maintenance.js",
       "skills-migrate": "bin/migrate.js"
     },
     exports: {
@@ -20068,7 +20069,7 @@ var init_package = __esm(() => {
     types: "./dist/index.d.ts",
     scripts: {
       clean: "rm -rf bin/ dist/",
-      build: "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
+      build: "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/server/maintenance.ts --outfile ./bin/maintenance.js --target bun && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
       "build:js": "rm -rf dist && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
       test: "bun test --timeout 30000",
       dev: "bun run ./src/cli/index.tsx",

package/bin/migrate.js

@@ -7,7 +7,7 @@ import { join as join5 } from "path";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.9.2",
+  version: "0.9.4",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -16,6 +16,7 @@ var package_default = {
     "skills-serve": "bin/server.js",
     "skills-server": "bin/server.js",
     "skills-worker": "bin/worker.js",
+    "skills-maintenance": "bin/maintenance.js",
     "skills-migrate": "bin/migrate.js"
   },
   exports: {
@@ -56,7 +57,7 @@ var package_default = {
   types: "./dist/index.d.ts",
   scripts: {
     clean: "rm -rf bin/ dist/",
-    build: "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
+    build: "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/server/maintenance.ts --outfile ./bin/maintenance.js --target bun && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
     "build:js": "rm -rf dist && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
     test: "bun test --timeout 30000",
     dev: "bun run ./src/cli/index.tsx",
@@ -1110,6 +1111,10 @@ class SkillLifecycleConflictError extends Error {
     this.name = "SkillLifecycleConflictError";
   }
 }
+function validOperatorScopeEnrollmentInput(input) {
+  const bounded = (value, max = 256) => typeof value === "string" && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value);
+  return bounded(input.keyId) && bounded(input.stationId) && bounded(input.orgId) && bounded(input.operationId) && bounded(input.manifestDigest, 64) && /^[a-f0-9]{64}$/.test(input.manifestDigest) && bounded(input.operatorJobId) && bounded(input.operatorTaskArn, 512) && input.expectedScopes.length > 0 && input.expectedScopes.length <= 32 && input.expectedScopes.every((scope) => bounded(scope, 128) && /^[a-z][a-z0-9_-]*:[a-z][a-z0-9_-]*$/.test(scope));
+}
 
 // src/lib/revision.ts
 import { createHash as createHash2 } from "crypto";
@@ -1257,6 +1262,54 @@ class SqliteSkillsStore {
     }
     return { kind: "updated", scopes };
   }
+  async enrollPublishScopeByOperator(input) {
+    if (!validOperatorScopeEnrollmentInput(input))
+      return { kind: "invalid" };
+    if (input.expectedScopes.includes("skills:publish"))
+      return { kind: "stale", scopes: input.expectedScopes };
+    const operation = this.get("SELECT org_id, target_id FROM skills_audit_events WHERE action = ? AND operator_operation_id = ? LIMIT 1", ["api_key_scopes_added", input.operationId]);
+    if (operation && (String(operation.org_id) !== input.orgId || String(operation.target_id) !== input.keyId))
+      return { kind: "target_mismatch" };
+    const row = this.get("SELECT id, org_id, name, scopes_json FROM api_keys WHERE id = ? AND revoked_at IS NULL LIMIT 1", [input.keyId]);
+    if (!row)
+      return { kind: "not_found" };
+    if (String(row.org_id) !== input.orgId)
+      return { kind: "target_mismatch" };
+    const current = parseScopes(row.scopes_json);
+    const prior = this.get("SELECT metadata_json FROM skills_audit_events WHERE action = ? AND target_type = ? AND target_id = ? AND json_extract(metadata_json, '$.operator_operation_id') = ? LIMIT 1", ["api_key_scopes_added", "api_key", input.keyId, input.operationId]);
+    if (prior) {
+      try {
+        if (JSON.parse(String(prior.metadata_json)).target_manifest_digest !== input.manifestDigest)
+          return { kind: "target_mismatch" };
+      } catch {
+        return { kind: "target_mismatch" };
+      }
+      return current.includes("skills:publish") ? { kind: "already_applied", scopes: current } : { kind: "stale", scopes: current };
+    }
+    if (current.length !== input.expectedScopes.length || current.some((scope, index) => scope !== input.expectedScopes[index]))
+      return { kind: "stale", scopes: current };
+    const scopes = [...current, "skills:publish"];
+    const tx = this.db.transaction(() => {
+      const changed = this.db.run("UPDATE api_keys SET scopes_json = ? WHERE id = ? AND org_id = ? AND revoked_at IS NULL AND scopes_json = ?", [JSON.stringify(scopes), input.keyId, input.orgId, JSON.stringify(input.expectedScopes)]);
+      if (changed.changes !== 1)
+        return false;
+      this.db.run("INSERT INTO skills_audit_events (org_id, user_id, api_key_id, action, target_type, target_id, operator_operation_id, metadata_json) VALUES (?, NULL, NULL, ?, ?, ?, ?, ?)", [input.orgId, "api_key_scopes_added", "api_key", input.keyId, input.operationId, JSON.stringify({ added: ["skills:publish"], scopes, operator_operation_id: input.operationId, operator_job_id: input.operatorJobId, operator_task_arn: input.operatorTaskArn, target_manifest_digest: input.manifestDigest, station_id: input.stationId })]);
+      return true;
+    });
+    if (!tx()) {
+      const latest = this.get("SELECT scopes_json FROM api_keys WHERE id = ? AND org_id = ? AND revoked_at IS NULL LIMIT 1", [input.keyId, input.orgId]);
+      return { kind: "stale", scopes: latest ? parseScopes(latest.scopes_json) : current };
+    }
+    return { kind: "updated", scopes };
+  }
+  async inspectOperatorScopeTarget(keyId, orgId) {
+    const row = this.get("SELECT org_id, scopes_json FROM api_keys WHERE id = ? AND revoked_at IS NULL LIMIT 1", [keyId]);
+    if (!row)
+      return { kind: "not_found" };
+    if (String(row.org_id) !== orgId)
+      return { kind: "target_mismatch" };
+    return { kind: "found", scopes: parseScopes(row.scopes_json) };
+  }
   async createRun(input) {
     if (input.idempotencyKey) {
       const existing = this.get("SELECT * FROM skills_runs WHERE org_id = ? AND idempotency_key = ? LIMIT 1", [input.principal.orgId, input.idempotencyKey]);

package/bin/server.js

@@ -24122,7 +24122,7 @@ var init_dist_es9 = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.9.2",
+  version: "0.9.4",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -24131,6 +24131,7 @@ var package_default = {
     "skills-serve": "bin/server.js",
     "skills-server": "bin/server.js",
     "skills-worker": "bin/worker.js",
+    "skills-maintenance": "bin/maintenance.js",
     "skills-migrate": "bin/migrate.js"
   },
   exports: {
@@ -24171,7 +24172,7 @@ var package_default = {
   types: "./dist/index.d.ts",
   scripts: {
     clean: "rm -rf bin/ dist/",
-    build: "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
+    build: "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/server/maintenance.ts --outfile ./bin/maintenance.js --target bun && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
     "build:js": "rm -rf dist && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
     test: "bun test --timeout 30000",
     dev: "bun run ./src/cli/index.tsx",
@@ -35319,6 +35320,10 @@ class SkillLifecycleConflictError extends Error {
     this.name = "SkillLifecycleConflictError";
   }
 }
+function validOperatorScopeEnrollmentInput(input) {
+  const bounded = (value, max = 256) => typeof value === "string" && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value);
+  return bounded(input.keyId) && bounded(input.stationId) && bounded(input.orgId) && bounded(input.operationId) && bounded(input.manifestDigest, 64) && /^[a-f0-9]{64}$/.test(input.manifestDigest) && bounded(input.operatorJobId) && bounded(input.operatorTaskArn, 512) && input.expectedScopes.length > 0 && input.expectedScopes.length <= 32 && input.expectedScopes.every((scope) => bounded(scope, 128) && /^[a-z][a-z0-9_-]*:[a-z][a-z0-9_-]*$/.test(scope));
+}
 
 // src/lib/revision.ts
 import { createHash as createHash5 } from "crypto";
@@ -35467,6 +35472,54 @@ class SqliteSkillsStore {
     }
     return { kind: "updated", scopes };
   }
+  async enrollPublishScopeByOperator(input) {
+    if (!validOperatorScopeEnrollmentInput(input))
+      return { kind: "invalid" };
+    if (input.expectedScopes.includes("skills:publish"))
+      return { kind: "stale", scopes: input.expectedScopes };
+    const operation = this.get("SELECT org_id, target_id FROM skills_audit_events WHERE action = ? AND operator_operation_id = ? LIMIT 1", ["api_key_scopes_added", input.operationId]);
+    if (operation && (String(operation.org_id) !== input.orgId || String(operation.target_id) !== input.keyId))
+      return { kind: "target_mismatch" };
+    const row = this.get("SELECT id, org_id, name, scopes_json FROM api_keys WHERE id = ? AND revoked_at IS NULL LIMIT 1", [input.keyId]);
+    if (!row)
+      return { kind: "not_found" };
+    if (String(row.org_id) !== input.orgId)
+      return { kind: "target_mismatch" };
+    const current = parseScopes(row.scopes_json);
+    const prior = this.get("SELECT metadata_json FROM skills_audit_events WHERE action = ? AND target_type = ? AND target_id = ? AND json_extract(metadata_json, '$.operator_operation_id') = ? LIMIT 1", ["api_key_scopes_added", "api_key", input.keyId, input.operationId]);
+    if (prior) {
+      try {
+        if (JSON.parse(String(prior.metadata_json)).target_manifest_digest !== input.manifestDigest)
+          return { kind: "target_mismatch" };
+      } catch {
+        return { kind: "target_mismatch" };
+      }
+      return current.includes("skills:publish") ? { kind: "already_applied", scopes: current } : { kind: "stale", scopes: current };
+    }
+    if (current.length !== input.expectedScopes.length || current.some((scope, index) => scope !== input.expectedScopes[index]))
+      return { kind: "stale", scopes: current };
+    const scopes = [...current, "skills:publish"];
+    const tx = this.db.transaction(() => {
+      const changed = this.db.run("UPDATE api_keys SET scopes_json = ? WHERE id = ? AND org_id = ? AND revoked_at IS NULL AND scopes_json = ?", [JSON.stringify(scopes), input.keyId, input.orgId, JSON.stringify(input.expectedScopes)]);
+      if (changed.changes !== 1)
+        return false;
+      this.db.run("INSERT INTO skills_audit_events (org_id, user_id, api_key_id, action, target_type, target_id, operator_operation_id, metadata_json) VALUES (?, NULL, NULL, ?, ?, ?, ?, ?)", [input.orgId, "api_key_scopes_added", "api_key", input.keyId, input.operationId, JSON.stringify({ added: ["skills:publish"], scopes, operator_operation_id: input.operationId, operator_job_id: input.operatorJobId, operator_task_arn: input.operatorTaskArn, target_manifest_digest: input.manifestDigest, station_id: input.stationId })]);
+      return true;
+    });
+    if (!tx()) {
+      const latest = this.get("SELECT scopes_json FROM api_keys WHERE id = ? AND org_id = ? AND revoked_at IS NULL LIMIT 1", [input.keyId, input.orgId]);
+      return { kind: "stale", scopes: latest ? parseScopes(latest.scopes_json) : current };
+    }
+    return { kind: "updated", scopes };
+  }
+  async inspectOperatorScopeTarget(keyId, orgId) {
+    const row = this.get("SELECT org_id, scopes_json FROM api_keys WHERE id = ? AND revoked_at IS NULL LIMIT 1", [keyId]);
+    if (!row)
+      return { kind: "not_found" };
+    if (String(row.org_id) !== orgId)
+      return { kind: "target_mismatch" };
+    return { kind: "found", scopes: parseScopes(row.scopes_json) };
+  }
   async createRun(input) {
     if (input.idempotencyKey) {
       const existing = this.get("SELECT * FROM skills_runs WHERE org_id = ? AND idempotency_key = ? LIMIT 1", [input.principal.orgId, input.idempotencyKey]);
@@ -42891,6 +42944,7 @@ class MemorySkillsStore {
   bundles = new Map;
   versions = new Map;
   pins = new Map;
+  operatorEnrollments = new Map;
   constructor(apiKeys = []) {
     for (const key of apiKeys)
       this.addApiKey(key.token, key.principal);
@@ -42920,6 +42974,41 @@ class MemorySkillsStore {
     }
     return { kind: "not_found" };
   }
+  async enrollPublishScopeByOperator(input) {
+    if (!validOperatorScopeEnrollmentInput(input))
+      return { kind: "invalid" };
+    const previous = this.operatorEnrollments.get(input.operationId);
+    if (previous) {
+      if (previous.keyId !== input.keyId || previous.manifestDigest !== input.manifestDigest)
+        return { kind: "target_mismatch" };
+      for (const target of this.apiKeys.values()) {
+        if (target.apiKeyId === input.keyId && target.orgId === input.orgId && target.scopes.includes("skills:publish")) {
+          return { kind: "already_applied", scopes: [...target.scopes] };
+        }
+      }
+      return { kind: "stale", scopes: [] };
+    }
+    for (const [hash2, target] of this.apiKeys) {
+      if (target.apiKeyId !== input.keyId || target.orgId !== input.orgId)
+        continue;
+      if (target.scopes.length !== input.expectedScopes.length || target.scopes.some((scope2, index) => scope2 !== input.expectedScopes[index])) {
+        return { kind: "stale", scopes: [...target.scopes] };
+      }
+      const scopes = target.scopes.includes("skills:publish") ? [...target.scopes] : [...target.scopes, "skills:publish"];
+      this.apiKeys.set(hash2, { ...target, scopes });
+      this.operatorEnrollments.set(input.operationId, { keyId: input.keyId, manifestDigest: input.manifestDigest });
+      return { kind: "updated", scopes };
+    }
+    return { kind: "not_found" };
+  }
+  async inspectOperatorScopeTarget(keyId, orgId) {
+    for (const target of this.apiKeys.values()) {
+      if (target.apiKeyId !== keyId)
+        continue;
+      return target.orgId === orgId ? { kind: "found", scopes: [...target.scopes] } : { kind: "target_mismatch" };
+    }
+    return { kind: "not_found" };
+  }
   async createRun(input) {
     const idemKey = input.idempotencyKey?.trim();
     const idemMapKey = idemKey ? `${input.principal.orgId}:${idemKey}` : undefined;
@@ -43334,24 +43423,98 @@ class PostgresSkillsStore {
       if (current.length !== expectedScopes.length || current.some((scope2, index) => scope2 !== expectedScopes[index])) {
         return { kind: "stale", scopes: current };
       }
-      const scopes = [...current, ...addScopes.filter((scope2) => !current.includes(scope2))];
-      const updated = await tx`
-        UPDATE api_keys SET scopes_json = ${JSON.stringify(scopes)}::jsonb
-        WHERE id = ${keyId} AND org_id = ${actor.orgId} AND revoked_at IS NULL
-          AND scopes_json = ${JSON.stringify(expectedScopes)}::jsonb
-        RETURNING scopes_json
-      `;
+      const updated = await this.casUpdateApiKeyScopes(tx, keyId, actor.orgId, expectedScopes, addScopes);
       if (!updated[0]) {
         const latest = await tx`SELECT scopes_json FROM api_keys WHERE id = ${keyId} AND org_id = ${actor.orgId} AND revoked_at IS NULL LIMIT 1`;
         return { kind: "stale", scopes: latest[0] ? parseJsonArray(latest[0].scopes_json) : current };
       }
       await tx`
         INSERT INTO skills_audit_events (org_id, user_id, api_key_id, action, target_type, target_id, metadata_json)
-        VALUES (${actor.orgId}, ${actor.userId}, ${actor.apiKeyId}, ${"api_key_scopes_added"}, ${"api_key"}, ${keyId}, ${JSON.stringify({ added: addScopes, scopes })}::jsonb)
+        VALUES (${actor.orgId}, ${actor.userId}, ${actor.apiKeyId}, ${"api_key_scopes_added"}, ${"api_key"}, ${keyId}, ${JSON.stringify({ added: addScopes, scopes: parseJsonArray(updated[0].scopes_json) })}::jsonb)
+      `;
+      return { kind: "updated", scopes: parseJsonArray(updated[0].scopes_json) };
+    });
+  }
+  async casUpdateApiKeyScopes(tx, keyId, orgId, expectedScopes, addScopes) {
+    const current = expectedScopes;
+    const scopes = [...current, ...addScopes.filter((scope2) => !current.includes(scope2))];
+    return tx`
+      UPDATE api_keys SET scopes_json = ${JSON.stringify(scopes)}::jsonb
+      WHERE id = ${keyId} AND org_id = ${orgId} AND revoked_at IS NULL
+        AND scopes_json = ${JSON.stringify(expectedScopes)}::jsonb
+      RETURNING scopes_json
+    `;
+  }
+  async enrollPublishScopeByOperator(input) {
+    if (!validOperatorScopeEnrollmentInput(input))
+      return { kind: "invalid" };
+    if (input.expectedScopes.includes("skills:publish"))
+      return { kind: "stale", scopes: input.expectedScopes };
+    return this.sql.begin(async (tx) => {
+      const operation = await tx`
+        SELECT org_id, target_id FROM skills_audit_events
+        WHERE action = ${"api_key_scopes_added"} AND operator_operation_id = ${input.operationId}
+        LIMIT 1
+      `;
+      if (operation[0] && (String(operation[0].org_id) !== input.orgId || String(operation[0].target_id) !== input.keyId))
+        return { kind: "target_mismatch" };
+      const rows = await tx`
+        SELECT id, org_id, name, scopes_json FROM api_keys
+        WHERE id = ${input.keyId} AND revoked_at IS NULL
+        FOR UPDATE
+      `;
+      const row = rows[0];
+      if (!row)
+        return { kind: "not_found" };
+      if (String(row.org_id) !== input.orgId)
+        return { kind: "target_mismatch" };
+      const current = parseJsonArray(row.scopes_json);
+      const prior = await tx`
+        SELECT metadata_json, metadata_json->>'target_manifest_digest' AS manifest_digest FROM skills_audit_events
+        WHERE action = ${"api_key_scopes_added"} AND target_type = ${"api_key"} AND target_id = ${input.keyId}
+          AND operator_operation_id = ${input.operationId}
+        LIMIT 1
+      `;
+      if (prior[0]) {
+        const priorMetadata = typeof prior[0].metadata_json === "string" ? JSON.parse(prior[0].metadata_json) : prior[0].metadata_json;
+        const priorDigest = prior[0].manifest_digest ?? priorMetadata?.target_manifest_digest;
+        if (String(priorDigest) !== input.manifestDigest)
+          return { kind: "target_mismatch" };
+        if (!current.includes("skills:publish"))
+          return { kind: "stale", scopes: current };
+        return { kind: "already_applied", scopes: current };
+      }
+      if (current.length !== input.expectedScopes.length || current.some((scope2, index) => scope2 !== input.expectedScopes[index])) {
+        return { kind: "stale", scopes: current };
+      }
+      const updated = await this.casUpdateApiKeyScopes(tx, input.keyId, input.orgId, input.expectedScopes, ["skills:publish"]);
+      if (!updated[0])
+        return { kind: "stale", scopes: current };
+      const scopes = parseJsonArray(updated[0].scopes_json);
+      await tx`
+        INSERT INTO skills_audit_events (org_id, user_id, api_key_id, action, target_type, target_id, operator_operation_id, metadata_json)
+        VALUES (${input.orgId}, NULL, NULL, ${"api_key_scopes_added"}, ${"api_key"}, ${input.keyId}, ${input.operationId}, ${JSON.stringify({
+        added: ["skills:publish"],
+        scopes,
+        operator_operation_id: input.operationId,
+        operator_job_id: input.operatorJobId,
+        operator_task_arn: input.operatorTaskArn,
+        target_manifest_digest: input.manifestDigest,
+        station_id: input.stationId
+      })}::jsonb)
       `;
       return { kind: "updated", scopes };
     });
   }
+  async inspectOperatorScopeTarget(keyId, orgId) {
+    const rows = await this.sql`SELECT org_id, scopes_json FROM api_keys WHERE id = ${keyId} AND revoked_at IS NULL LIMIT 1`;
+    const row = rows[0];
+    if (!row)
+      return { kind: "not_found" };
+    if (String(row.org_id) !== orgId)
+      return { kind: "target_mismatch" };
+    return { kind: "found", scopes: parseJsonArray(row.scopes_json) };
+  }
   async withContext(orgId, worker, fn) {
     return this.sql.begin(async (tx) => {
       await tx`SELECT set_config('app.skills_org_id', ${orgId ?? ""}, true)`;

package/bin/worker.js

@@ -24125,7 +24125,7 @@ import { randomUUID as randomUUID6 } from "crypto";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.9.2",
+  version: "0.9.4",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -24134,6 +24134,7 @@ var package_default = {
     "skills-serve": "bin/server.js",
     "skills-server": "bin/server.js",
     "skills-worker": "bin/worker.js",
+    "skills-maintenance": "bin/maintenance.js",
     "skills-migrate": "bin/migrate.js"
   },
   exports: {
@@ -24174,7 +24175,7 @@ var package_default = {
   types: "./dist/index.d.ts",
   scripts: {
     clean: "rm -rf bin/ dist/",
-    build: "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
+    build: "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/server/maintenance.ts --outfile ./bin/maintenance.js --target bun && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
     "build:js": "rm -rf dist && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
     test: "bun test --timeout 30000",
     dev: "bun run ./src/cli/index.tsx",
@@ -35067,6 +35068,10 @@ class SkillLifecycleConflictError extends Error {
     this.name = "SkillLifecycleConflictError";
   }
 }
+function validOperatorScopeEnrollmentInput(input) {
+  const bounded = (value, max = 256) => typeof value === "string" && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value);
+  return bounded(input.keyId) && bounded(input.stationId) && bounded(input.orgId) && bounded(input.operationId) && bounded(input.manifestDigest, 64) && /^[a-f0-9]{64}$/.test(input.manifestDigest) && bounded(input.operatorJobId) && bounded(input.operatorTaskArn, 512) && input.expectedScopes.length > 0 && input.expectedScopes.length <= 32 && input.expectedScopes.every((scope) => bounded(scope, 128) && /^[a-z][a-z0-9_-]*:[a-z][a-z0-9_-]*$/.test(scope));
+}
 
 // src/lib/revision.ts
 import { createHash as createHash4 } from "crypto";
@@ -35214,6 +35219,54 @@ class SqliteSkillsStore {
     }
     return { kind: "updated", scopes };
   }
+  async enrollPublishScopeByOperator(input) {
+    if (!validOperatorScopeEnrollmentInput(input))
+      return { kind: "invalid" };
+    if (input.expectedScopes.includes("skills:publish"))
+      return { kind: "stale", scopes: input.expectedScopes };
+    const operation = this.get("SELECT org_id, target_id FROM skills_audit_events WHERE action = ? AND operator_operation_id = ? LIMIT 1", ["api_key_scopes_added", input.operationId]);
+    if (operation && (String(operation.org_id) !== input.orgId || String(operation.target_id) !== input.keyId))
+      return { kind: "target_mismatch" };
+    const row = this.get("SELECT id, org_id, name, scopes_json FROM api_keys WHERE id = ? AND revoked_at IS NULL LIMIT 1", [input.keyId]);
+    if (!row)
+      return { kind: "not_found" };
+    if (String(row.org_id) !== input.orgId)
+      return { kind: "target_mismatch" };
+    const current = parseScopes(row.scopes_json);
+    const prior = this.get("SELECT metadata_json FROM skills_audit_events WHERE action = ? AND target_type = ? AND target_id = ? AND json_extract(metadata_json, '$.operator_operation_id') = ? LIMIT 1", ["api_key_scopes_added", "api_key", input.keyId, input.operationId]);
+    if (prior) {
+      try {
+        if (JSON.parse(String(prior.metadata_json)).target_manifest_digest !== input.manifestDigest)
+          return { kind: "target_mismatch" };
+      } catch {
+        return { kind: "target_mismatch" };
+      }
+      return current.includes("skills:publish") ? { kind: "already_applied", scopes: current } : { kind: "stale", scopes: current };
+    }
+    if (current.length !== input.expectedScopes.length || current.some((scope, index) => scope !== input.expectedScopes[index]))
+      return { kind: "stale", scopes: current };
+    const scopes = [...current, "skills:publish"];
+    const tx = this.db.transaction(() => {
+      const changed = this.db.run("UPDATE api_keys SET scopes_json = ? WHERE id = ? AND org_id = ? AND revoked_at IS NULL AND scopes_json = ?", [JSON.stringify(scopes), input.keyId, input.orgId, JSON.stringify(input.expectedScopes)]);
+      if (changed.changes !== 1)
+        return false;
+      this.db.run("INSERT INTO skills_audit_events (org_id, user_id, api_key_id, action, target_type, target_id, operator_operation_id, metadata_json) VALUES (?, NULL, NULL, ?, ?, ?, ?, ?)", [input.orgId, "api_key_scopes_added", "api_key", input.keyId, input.operationId, JSON.stringify({ added: ["skills:publish"], scopes, operator_operation_id: input.operationId, operator_job_id: input.operatorJobId, operator_task_arn: input.operatorTaskArn, target_manifest_digest: input.manifestDigest, station_id: input.stationId })]);
+      return true;
+    });
+    if (!tx()) {
+      const latest = this.get("SELECT scopes_json FROM api_keys WHERE id = ? AND org_id = ? AND revoked_at IS NULL LIMIT 1", [input.keyId, input.orgId]);
+      return { kind: "stale", scopes: latest ? parseScopes(latest.scopes_json) : current };
+    }
+    return { kind: "updated", scopes };
+  }
+  async inspectOperatorScopeTarget(keyId, orgId) {
+    const row = this.get("SELECT org_id, scopes_json FROM api_keys WHERE id = ? AND revoked_at IS NULL LIMIT 1", [keyId]);
+    if (!row)
+      return { kind: "not_found" };
+    if (String(row.org_id) !== orgId)
+      return { kind: "target_mismatch" };
+    return { kind: "found", scopes: parseScopes(row.scopes_json) };
+  }
   async createRun(input) {
     if (input.idempotencyKey) {
       const existing = this.get("SELECT * FROM skills_runs WHERE org_id = ? AND idempotency_key = ? LIMIT 1", [input.principal.orgId, input.idempotencyKey]);
@@ -36427,6 +36480,7 @@ class MemorySkillsStore {
   bundles = new Map;
   versions = new Map;
   pins = new Map;
+  operatorEnrollments = new Map;
   constructor(apiKeys = []) {
     for (const key of apiKeys)
       this.addApiKey(key.token, key.principal);
@@ -36456,6 +36510,41 @@ class MemorySkillsStore {
     }
     return { kind: "not_found" };
   }
+  async enrollPublishScopeByOperator(input) {
+    if (!validOperatorScopeEnrollmentInput(input))
+      return { kind: "invalid" };
+    const previous = this.operatorEnrollments.get(input.operationId);
+    if (previous) {
+      if (previous.keyId !== input.keyId || previous.manifestDigest !== input.manifestDigest)
+        return { kind: "target_mismatch" };
+      for (const target of this.apiKeys.values()) {
+        if (target.apiKeyId === input.keyId && target.orgId === input.orgId && target.scopes.includes("skills:publish")) {
+          return { kind: "already_applied", scopes: [...target.scopes] };
+        }
+      }
+      return { kind: "stale", scopes: [] };
+    }
+    for (const [hash, target] of this.apiKeys) {
+      if (target.apiKeyId !== input.keyId || target.orgId !== input.orgId)
+        continue;
+      if (target.scopes.length !== input.expectedScopes.length || target.scopes.some((scope, index) => scope !== input.expectedScopes[index])) {
+        return { kind: "stale", scopes: [...target.scopes] };
+      }
+      const scopes = target.scopes.includes("skills:publish") ? [...target.scopes] : [...target.scopes, "skills:publish"];
+      this.apiKeys.set(hash, { ...target, scopes });
+      this.operatorEnrollments.set(input.operationId, { keyId: input.keyId, manifestDigest: input.manifestDigest });
+      return { kind: "updated", scopes };
+    }
+    return { kind: "not_found" };
+  }
+  async inspectOperatorScopeTarget(keyId, orgId) {
+    for (const target of this.apiKeys.values()) {
+      if (target.apiKeyId !== keyId)
+        continue;
+      return target.orgId === orgId ? { kind: "found", scopes: [...target.scopes] } : { kind: "target_mismatch" };
+    }
+    return { kind: "not_found" };
+  }
   async createRun(input) {
     const idemKey = input.idempotencyKey?.trim();
     const idemMapKey = idemKey ? `${input.principal.orgId}:${idemKey}` : undefined;
@@ -36870,24 +36959,98 @@ class PostgresSkillsStore {
       if (current.length !== expectedScopes.length || current.some((scope, index) => scope !== expectedScopes[index])) {
         return { kind: "stale", scopes: current };
       }
-      const scopes = [...current, ...addScopes.filter((scope) => !current.includes(scope))];
-      const updated = await tx`
-        UPDATE api_keys SET scopes_json = ${JSON.stringify(scopes)}::jsonb
-        WHERE id = ${keyId} AND org_id = ${actor.orgId} AND revoked_at IS NULL
-          AND scopes_json = ${JSON.stringify(expectedScopes)}::jsonb
-        RETURNING scopes_json
-      `;
+      const updated = await this.casUpdateApiKeyScopes(tx, keyId, actor.orgId, expectedScopes, addScopes);
       if (!updated[0]) {
         const latest = await tx`SELECT scopes_json FROM api_keys WHERE id = ${keyId} AND org_id = ${actor.orgId} AND revoked_at IS NULL LIMIT 1`;
         return { kind: "stale", scopes: latest[0] ? parseJsonArray(latest[0].scopes_json) : current };
       }
       await tx`
         INSERT INTO skills_audit_events (org_id, user_id, api_key_id, action, target_type, target_id, metadata_json)
-        VALUES (${actor.orgId}, ${actor.userId}, ${actor.apiKeyId}, ${"api_key_scopes_added"}, ${"api_key"}, ${keyId}, ${JSON.stringify({ added: addScopes, scopes })}::jsonb)
+        VALUES (${actor.orgId}, ${actor.userId}, ${actor.apiKeyId}, ${"api_key_scopes_added"}, ${"api_key"}, ${keyId}, ${JSON.stringify({ added: addScopes, scopes: parseJsonArray(updated[0].scopes_json) })}::jsonb)
+      `;
+      return { kind: "updated", scopes: parseJsonArray(updated[0].scopes_json) };
+    });
+  }
+  async casUpdateApiKeyScopes(tx, keyId, orgId, expectedScopes, addScopes) {
+    const current = expectedScopes;
+    const scopes = [...current, ...addScopes.filter((scope) => !current.includes(scope))];
+    return tx`
+      UPDATE api_keys SET scopes_json = ${JSON.stringify(scopes)}::jsonb
+      WHERE id = ${keyId} AND org_id = ${orgId} AND revoked_at IS NULL
+        AND scopes_json = ${JSON.stringify(expectedScopes)}::jsonb
+      RETURNING scopes_json
+    `;
+  }
+  async enrollPublishScopeByOperator(input) {
+    if (!validOperatorScopeEnrollmentInput(input))
+      return { kind: "invalid" };
+    if (input.expectedScopes.includes("skills:publish"))
+      return { kind: "stale", scopes: input.expectedScopes };
+    return this.sql.begin(async (tx) => {
+      const operation = await tx`
+        SELECT org_id, target_id FROM skills_audit_events
+        WHERE action = ${"api_key_scopes_added"} AND operator_operation_id = ${input.operationId}
+        LIMIT 1
+      `;
+      if (operation[0] && (String(operation[0].org_id) !== input.orgId || String(operation[0].target_id) !== input.keyId))
+        return { kind: "target_mismatch" };
+      const rows = await tx`
+        SELECT id, org_id, name, scopes_json FROM api_keys
+        WHERE id = ${input.keyId} AND revoked_at IS NULL
+        FOR UPDATE
+      `;
+      const row = rows[0];
+      if (!row)
+        return { kind: "not_found" };
+      if (String(row.org_id) !== input.orgId)
+        return { kind: "target_mismatch" };
+      const current = parseJsonArray(row.scopes_json);
+      const prior = await tx`
+        SELECT metadata_json, metadata_json->>'target_manifest_digest' AS manifest_digest FROM skills_audit_events
+        WHERE action = ${"api_key_scopes_added"} AND target_type = ${"api_key"} AND target_id = ${input.keyId}
+          AND operator_operation_id = ${input.operationId}
+        LIMIT 1
+      `;
+      if (prior[0]) {
+        const priorMetadata = typeof prior[0].metadata_json === "string" ? JSON.parse(prior[0].metadata_json) : prior[0].metadata_json;
+        const priorDigest = prior[0].manifest_digest ?? priorMetadata?.target_manifest_digest;
+        if (String(priorDigest) !== input.manifestDigest)
+          return { kind: "target_mismatch" };
+        if (!current.includes("skills:publish"))
+          return { kind: "stale", scopes: current };
+        return { kind: "already_applied", scopes: current };
+      }
+      if (current.length !== input.expectedScopes.length || current.some((scope, index) => scope !== input.expectedScopes[index])) {
+        return { kind: "stale", scopes: current };
+      }
+      const updated = await this.casUpdateApiKeyScopes(tx, input.keyId, input.orgId, input.expectedScopes, ["skills:publish"]);
+      if (!updated[0])
+        return { kind: "stale", scopes: current };
+      const scopes = parseJsonArray(updated[0].scopes_json);
+      await tx`
+        INSERT INTO skills_audit_events (org_id, user_id, api_key_id, action, target_type, target_id, operator_operation_id, metadata_json)
+        VALUES (${input.orgId}, NULL, NULL, ${"api_key_scopes_added"}, ${"api_key"}, ${input.keyId}, ${input.operationId}, ${JSON.stringify({
+        added: ["skills:publish"],
+        scopes,
+        operator_operation_id: input.operationId,
+        operator_job_id: input.operatorJobId,
+        operator_task_arn: input.operatorTaskArn,
+        target_manifest_digest: input.manifestDigest,
+        station_id: input.stationId
+      })}::jsonb)
       `;
       return { kind: "updated", scopes };
     });
   }
+  async inspectOperatorScopeTarget(keyId, orgId) {
+    const rows = await this.sql`SELECT org_id, scopes_json FROM api_keys WHERE id = ${keyId} AND revoked_at IS NULL LIMIT 1`;
+    const row = rows[0];
+    if (!row)
+      return { kind: "not_found" };
+    if (String(row.org_id) !== orgId)
+      return { kind: "target_mismatch" };
+    return { kind: "found", scopes: parseJsonArray(row.scopes_json) };
+  }
   async withContext(orgId, worker, fn) {
     return this.sql.begin(async (tx) => {
       await tx`SELECT set_config('app.skills_org_id', ${orgId ?? ""}, true)`;