@anhlp/alp-core 0.0.0-beta.2 → 0.0.1-beta.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (158) hide show
  1. package/dist/backup.js +106 -4
  2. package/dist/bridges.d.ts +26 -0
  3. package/dist/bridges.js +96 -0
  4. package/dist/gate-ledger.d.ts +30 -0
  5. package/dist/gate-ledger.js +99 -0
  6. package/dist/index.d.ts +1 -0
  7. package/dist/index.js +2 -0
  8. package/dist/library-edit.d.ts +57 -5
  9. package/dist/library-edit.js +216 -11
  10. package/dist/library.d.ts +14 -1
  11. package/dist/library.js +73 -5
  12. package/dist/migrations.js +1 -1
  13. package/dist/models.d.ts +74 -0
  14. package/dist/models.js +67 -1
  15. package/dist/packaged.d.ts +122 -0
  16. package/dist/packaged.js +125 -0
  17. package/dist/packs.d.ts +57 -0
  18. package/dist/packs.js +247 -0
  19. package/dist/permissions.d.ts +3 -2
  20. package/dist/permissions.js +6 -3
  21. package/dist/profiles.js +6 -6
  22. package/dist/providers.d.ts +4 -5
  23. package/dist/providers.js +26 -5
  24. package/dist/skill-validate.d.ts +85 -0
  25. package/dist/skill-validate.js +298 -0
  26. package/dist/task-rows.d.ts +5 -0
  27. package/dist/task-rows.js +1 -1
  28. package/dist/tasks.d.ts +23 -4
  29. package/dist/tasks.js +103 -9
  30. package/dist/types.d.ts +3 -0
  31. package/dist/upgrade.d.ts +10 -0
  32. package/dist/upgrade.js +112 -6
  33. package/dist/user-settings.d.ts +2 -0
  34. package/dist/user-settings.js +40 -1
  35. package/dist/user-worktree.d.ts +29 -0
  36. package/dist/user-worktree.js +242 -0
  37. package/dist/validation.d.ts +1 -0
  38. package/dist/validation.js +35 -13
  39. package/package.json +34 -2
  40. package/src/backup.js +106 -5
  41. package/src/bridges.js +113 -0
  42. package/src/gate-ledger.js +125 -0
  43. package/src/index.js +1 -0
  44. package/src/library-edit.js +227 -12
  45. package/src/library.js +96 -6
  46. package/src/migrations.js +1 -1
  47. package/src/models.js +87 -1
  48. package/src/packaged.js +207 -0
  49. package/src/packs.js +246 -0
  50. package/src/permissions.d.ts +3 -2
  51. package/src/permissions.js +13 -3
  52. package/src/profiles.js +7 -7
  53. package/src/providers.js +23 -7
  54. package/src/resolver.js +1 -1
  55. package/src/skill-validate.js +287 -0
  56. package/src/task-rows.js +1 -1
  57. package/src/tasks.d.ts +23 -4
  58. package/src/tasks.js +137 -10
  59. package/src/types.d.ts +3 -0
  60. package/src/upgrade.js +54 -6
  61. package/src/user-settings.d.ts +2 -0
  62. package/src/user-settings.js +51 -1
  63. package/src/user-worktree.js +259 -0
  64. package/src/validation.d.ts +1 -0
  65. package/src/validation.js +43 -14
  66. package/templates/ALP.md +52 -52
  67. package/templates/agents/lead/AGENT.md +77 -74
  68. package/templates/agents/main/AGENT.md +153 -141
  69. package/templates/agents/oracle/AGENT.md +38 -37
  70. package/templates/agents/peer/AGENT.md +56 -52
  71. package/templates/agents/reviewer/AGENT.md +63 -65
  72. package/templates/agents/supervisor/AGENT.md +63 -63
  73. package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
  74. package/templates/packs/architecture/agents/architect/agent.json +5 -0
  75. package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
  76. package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
  77. package/templates/packs/architecture/pack.json +7 -0
  78. package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
  79. package/templates/packs/architecture/teams/blueprint/team.json +19 -0
  80. package/templates/packs/backend/pack.json +6 -0
  81. package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
  82. package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
  83. package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
  84. package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
  85. package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
  86. package/templates/packs/backend/skills/databases/SKILL.md +103 -0
  87. package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
  88. package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
  89. package/templates/packs/design/pack.json +6 -0
  90. package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
  91. package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
  92. package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
  93. package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
  94. package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
  95. package/templates/packs/frontend/pack.json +6 -0
  96. package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
  97. package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
  98. package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
  99. package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
  100. package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
  101. package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
  102. package/templates/packs/integration/pack.json +6 -0
  103. package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
  104. package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
  105. package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
  106. package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
  107. package/templates/packs/operations/pack.json +6 -0
  108. package/templates/packs/operations/skills/devops/SKILL.md +85 -0
  109. package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
  110. package/templates/packs/operations/skills/devops/references/containers.md +85 -0
  111. package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
  112. package/templates/packs/operations/skills/devops/references/observability.md +86 -0
  113. package/templates/packs/quality/pack.json +6 -0
  114. package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
  115. package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
  116. package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
  117. package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
  118. package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
  119. package/templates/role-skills.json +4 -4
  120. package/templates/skills/architecture-docs/SKILL.md +81 -0
  121. package/templates/skills/architecture-docs/references/adr.md +62 -0
  122. package/templates/skills/architecture-docs/references/diagrams.md +60 -0
  123. package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
  124. package/templates/skills/bug-loop/SKILL.md +41 -40
  125. package/templates/skills/bug-loop/references/test-proof.md +21 -19
  126. package/templates/skills/compact/SKILL.md +34 -0
  127. package/templates/skills/curate/SKILL.md +36 -0
  128. package/templates/skills/feature-architecture/SKILL.md +90 -0
  129. package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
  130. package/templates/skills/feature-architecture/references/feature-design.md +69 -0
  131. package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
  132. package/templates/skills/goal-griller/SKILL.md +27 -27
  133. package/templates/skills/prompt-leverage/SKILL.md +29 -27
  134. package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
  135. package/templates/skills/release-readiness/SKILL.md +83 -0
  136. package/templates/skills/release-readiness/references/checklist.md +40 -0
  137. package/templates/skills/release-readiness/references/verdict-template.md +53 -0
  138. package/templates/skills/safe-refactor/SKILL.md +84 -0
  139. package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
  140. package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
  141. package/templates/skills/security-review/SKILL.md +87 -0
  142. package/templates/skills/security-review/references/checklist.md +74 -0
  143. package/templates/skills/security-review/references/severity.md +61 -0
  144. package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
  145. package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
  146. package/templates/skills/skill-authoring/SKILL.md +84 -0
  147. package/templates/skills/skill-authoring/references/evaluation.md +45 -0
  148. package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
  149. package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
  150. package/templates/skills/smart-commits/SKILL.md +37 -36
  151. package/templates/skills/test-strategy/SKILL.md +83 -0
  152. package/templates/skills/test-strategy/references/contract-tests.md +46 -0
  153. package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
  154. package/templates/skills/xia/SKILL.md +40 -38
  155. package/templates/teams/cafe/HOUSE_RULES.md +1 -1
  156. package/templates/teams/cafe/team.json +1 -1
  157. package/templates/teams/pho/HOUSE_RULES.md +1 -1
  158. package/templates/teams/pho/team.json +1 -1
package/dist/backup.js CHANGED
@@ -13,10 +13,15 @@ import { STATE_SCHEMA, assertStateSupported, readStateSchema } from "./state-sch
13
13
  import { withTaskLock } from "./tasks.js";
14
14
  var BACKUP_FORMAT = 1;
15
15
  var BACKUP_EXTENSION = ".alpbackup";
16
- var STATE_UNITS = ["state/schema.json", "state/sessions", "state/timeline", "state/receipts", "state/recall.json", "state/pause.json", "state/trust.json", "state/web-workspaces.json"];
16
+ var RESULT_LEDGER = "state/assignment-results.json";
17
+ var RESULT_MARKER = `${RESULT_LEDGER}.initialized`;
18
+ var DESTINATIONS = "worktree-destinations.json";
19
+ var QUARANTINED_DESTINATIONS = "state/worktree-destinations.quarantined.json";
20
+ var STATE_UNITS = [RESULT_LEDGER, RESULT_MARKER, "state/assignment-archive", "state/schema.json", "state/sessions", "state/timeline", "state/receipts", "state/recall.json", "state/pause.json", "state/trust.json", "state/web-workspaces.json"];
17
21
  var CLEARED_UNITS = ["state/live.json", "state/migration.json"];
18
22
  var HOME_UNITS = [
19
23
  ...STATE_UNITS,
24
+ DESTINATIONS,
20
25
  "settings.json",
21
26
  "library.json",
22
27
  "role-skills.json",
@@ -378,6 +383,101 @@ async function holdTaskLocks(roots, work) {
378
383
  clearInterval(touch);
379
384
  }
380
385
  }
386
+ async function prepareWorkspaceRestore(home, root, units, warnings) {
387
+ const relevant = [RESULT_LEDGER, RESULT_MARKER, DESTINATIONS, "state/sessions", "state/web-workspaces.json"];
388
+ const restorable = units.filter((unit) => unit.path !== QUARANTINED_DESTINATIONS);
389
+ if (!units.some((unit) => relevant.includes(unit.path))) return restorable;
390
+ for (const base of [home, root]) {
391
+ const info = await lstat(path.join(base, "state")).catch((error) => {
392
+ if (error.code === "ENOENT") return void 0;
393
+ throw error;
394
+ });
395
+ if (info && !info.isDirectory()) throw invalid("workspace state must be a real directory");
396
+ }
397
+ const result = restorable.filter((unit) => ![RESULT_LEDGER, RESULT_MARKER, DESTINATIONS, "state/web-workspaces.json"].includes(unit.path));
398
+ async function regular(base, unit, declared) {
399
+ if (declared && declared.kind === "absent") return void 0;
400
+ const file = path.join(base, unit);
401
+ const info = await lstat(file).catch((error) => {
402
+ if (error.code === "ENOENT") return void 0;
403
+ throw error;
404
+ });
405
+ if (!info) {
406
+ if (declared) throw invalid(`${unit} is declared but missing from the backup`);
407
+ return void 0;
408
+ }
409
+ if (!info.isFile()) throw invalid(`${unit} must be a regular file for a workspace restore`);
410
+ return readFile(file, "utf8");
411
+ }
412
+ const incoming = async (unit) => {
413
+ const declared = units.find((entry) => entry.path === unit);
414
+ return declared ? regular(root, unit, declared) : void 0;
415
+ };
416
+ const owners = /* @__PURE__ */ new Map();
417
+ let hasLedger = false;
418
+ for (const text of [await incoming(RESULT_LEDGER), await regular(home, RESULT_LEDGER)]) {
419
+ if (text === void 0) continue;
420
+ let value;
421
+ try {
422
+ value = JSON.parse(text);
423
+ } catch {
424
+ throw invalid("assignment result ledger is not readable JSON; repair it before restoring");
425
+ }
426
+ const absolute = (value2) => typeof value2 === "string" && path.isAbsolute(value2);
427
+ if (value?.version !== 1 || !Array.isArray(value.workspaces) || !value.workspaces.every(absolute) || !Array.isArray(value.results) || !value.results.every((entry) => entry && typeof entry.assignmentId === "string" && absolute(entry.checkout) && (entry.worktree === void 0 || absolute(entry.worktree))))
428
+ throw invalid("assignment result ledger has an unsupported or invalid shape");
429
+ hasLedger = true;
430
+ for (const entry of value.results) {
431
+ const owner = { assignmentId: entry.assignmentId, checkout: entry.checkout, ...entry.worktree === void 0 ? {} : { worktree: entry.worktree } };
432
+ const previous = owners.get(owner.assignmentId);
433
+ const identity = (value2) => JSON.stringify({ assignmentId: value2.assignmentId, checkout: value2.checkout, worktree: value2.worktree });
434
+ if (previous && identity(previous) !== identity(owner)) throw invalid("assignment result ownership conflicts with current data; reconcile it before restoring");
435
+ const evidence = (value2) => !!value2 && typeof value2 === "object" && !Array.isArray(value2) && ["agent", "status", "finishedAt", "project", "brief", "summary"].every((key) => typeof value2[key] === "string") && Array.isArray(value2.requesters) && value2.requesters.every((id) => typeof id === "string") && (value2.taskId === void 0 || typeof value2.taskId === "string");
436
+ const result2 = evidence(entry.result) ? entry.result : previous?.result;
437
+ owners.set(owner.assignmentId, { ...owner, ...result2 === void 0 ? {} : { result: result2 } });
438
+ }
439
+ }
440
+ const markers = [await incoming(RESULT_MARKER), await regular(home, RESULT_MARKER)];
441
+ if (markers.some((text) => text !== void 0 && text !== "1\n")) throw invalid("assignment result initialized marker is invalid");
442
+ await mkdir(path.join(root, "state"), { recursive: true, mode: 448 });
443
+ if (hasLedger) await writeAtomic(path.join(root, RESULT_LEDGER), JSON.stringify({ version: 1, workspaces: [], results: [...owners.values()] }) + "\n");
444
+ result.push({ path: RESULT_LEDGER, kind: hasLedger ? "file" : "absent" });
445
+ const initialized = markers.some((text) => text !== void 0);
446
+ if (initialized) await writeAtomic(path.join(root, RESULT_MARKER), "1\n");
447
+ result.push({ path: RESULT_MARKER, kind: initialized ? "file" : "absent" });
448
+ const mappings = await incoming(DESTINATIONS);
449
+ if (mappings !== void 0) {
450
+ await writeAtomic(path.join(root, QUARANTINED_DESTINATIONS), mappings);
451
+ result.push({ path: QUARANTINED_DESTINATIONS, kind: "file" });
452
+ }
453
+ result.push({ path: DESTINATIONS, kind: "absent" });
454
+ const registryUnit = "state/web-workspaces.json";
455
+ const registryDeclaration = units.find((unit) => unit.path === registryUnit);
456
+ const registryText = registryDeclaration ? await incoming(registryUnit) : await regular(home, registryUnit);
457
+ if (registryText !== void 0) {
458
+ let registry;
459
+ try {
460
+ registry = JSON.parse(registryText);
461
+ } catch {
462
+ throw invalid("workspace registry is not readable JSON; repair it before restoring");
463
+ }
464
+ const epoch = `restore-${randomBytes(16).toString("hex")}`;
465
+ let revoked = false;
466
+ const revoke = (value) => {
467
+ if (!value || typeof value !== "object") return;
468
+ if (Object.hasOwn(value, "grantEpoch")) {
469
+ value.grantEpoch = epoch;
470
+ revoked = true;
471
+ }
472
+ for (const child of Object.values(value)) revoke(child);
473
+ };
474
+ revoke(registry);
475
+ await writeAtomic(path.join(root, registryUnit), revoked ? JSON.stringify(registry) + "\n" : registryText);
476
+ result.push({ path: registryUnit, kind: "file" });
477
+ } else if (registryDeclaration) result.push({ path: registryUnit, kind: "absent" });
478
+ if (hasLedger || initialized || mappings !== void 0 || await exists(path.join(home, DESTINATIONS))) warnings.push("Workspace restore retains assignment owners but clears checkout birth certification; old targets require an audited migration. Worktree destination mappings are inactive and require explicit host approval; archived mapping evidence is in state/worktree-destinations.quarantined.json. Historical checkout grants remain revoked after reapproval.");
479
+ return result;
480
+ }
381
481
  async function restoreBackup({ home, file, projects = true, safety = true, clearLive = true, replaceNewer = false, by = "alp", beforeSwap }) {
382
482
  const interrupted = await recoverInterruptedRestore(home);
383
483
  try {
@@ -392,6 +492,7 @@ async function restoreBackup({ home, file, projects = true, safety = true, clear
392
492
  const warnings = [];
393
493
  const areaBase = (area) => area === "home" ? home : header.projects[Number(area.slice(8))].root;
394
494
  const directories = [];
495
+ let homeUnits;
395
496
  const journal = { version: 1, id, file: path.resolve(file), by, startedAt: (/* @__PURE__ */ new Date()).toISOString(), phase: "staging", units: [], staging: [], created: [], locks: [] };
396
497
  const record = () => writeAtomic(journalFile(home), JSON.stringify(journal) + "\n");
397
498
  const abandon = async () => {
@@ -443,6 +544,7 @@ async function restoreBackup({ home, file, projects = true, safety = true, clear
443
544
  };
444
545
  }
445
546
  });
547
+ homeUnits = await prepareWorkspaceRestore(home, staging.get("home"), header.units, warnings);
446
548
  for (const [directory, mode] of directories.reverse()) if (Number.isSafeInteger(mode)) await chmod(directory, mode & 511 | 448).catch(() => {
447
549
  });
448
550
  } catch (error) {
@@ -463,8 +565,8 @@ async function restoreBackup({ home, file, projects = true, safety = true, clear
463
565
  const plan = [];
464
566
  for (const [area, root] of staging) {
465
567
  const base = areaBase(area);
466
- const units = area === "home" ? header.units : header.projects[Number(area.slice(8))].units;
467
- const known = area === "home" ? HOME_UNITS : PROJECT_UNITS;
568
+ const units = area === "home" ? homeUnits : header.projects[Number(area.slice(8))].units;
569
+ const known = area === "home" ? [...HOME_UNITS, QUARANTINED_DESTINATIONS] : PROJECT_UNITS;
468
570
  for (const unit of units) {
469
571
  if (!known.includes(unit.path)) {
470
572
  warnings.push(`${unit.path} is not a unit this ALP restores; left as it is`);
@@ -489,7 +591,7 @@ async function restoreBackup({ home, file, projects = true, safety = true, clear
489
591
  let safetyFile;
490
592
  if (safety) {
491
593
  try {
492
- safetyFile = await automaticBackup(home, "pre-restore", { units: header.units.map((unit) => unit.path).filter((unit) => HOME_UNITS.includes(unit)), projects: roots, by });
594
+ safetyFile = await automaticBackup(home, "pre-restore", { units: [.../* @__PURE__ */ new Set([...header.units.map((unit) => unit.path), ...homeUnits.map((unit) => unit.path)])].filter((unit) => HOME_UNITS.includes(unit) || unit === QUARANTINED_DESTINATIONS), projects: roots, by });
493
595
  } catch (error) {
494
596
  await abandon();
495
597
  throw new AlpError("RESTORE_SAFETY_BACKUP_FAILED", `could not save the current data before restoring (${error?.message ?? error}); nothing was changed`, { cause: error });
@@ -0,0 +1,26 @@
1
+ /** Runs a bridge in this process, as `node -e` would. @param {string} kind */
2
+ export function runBridge(kind: string): void;
3
+ /**
4
+ * The command an agent CLI runs to start a bridge: `node -e <source>` under this Node.
5
+ * @param {'acp' | 'antigravity'} kind
6
+ * @returns {{ command: string, args: string[] }}
7
+ */
8
+ export function bridgeCommand(kind: "acp" | "antigravity"): {
9
+ command: string;
10
+ args: string[];
11
+ };
12
+ /**
13
+ * Whether an MCP server entry is one of ALP's bridge launchers: the `-e` source, or `alp bridge <kind>`
14
+ * as the single-file executable of 0.0.1-beta.5/6 wrote it (only when its command is named alp, so another server is kept).
15
+ * @param {'acp' | 'antigravity'} kind
16
+ * @param {unknown} args
17
+ * @param {unknown} [command]
18
+ */
19
+ export function isBridgeArgs(kind: "acp" | "antigravity", args: unknown, command?: unknown): boolean;
20
+ /**
21
+ * The stdio MCP bridges an agent CLI starts to reach alpd's tools (ACP agents and Antigravity).
22
+ * They run as `node -e <source>`; `alp bridge acp|antigravity` (which calls runBridge) remains for
23
+ * the MCP entries the single-file executable of 0.0.1-beta.5/6 wrote.
24
+ */
25
+ export const ACP_BRIDGE: "\nconst net = require('node:net');\nconst readline = require('node:readline');\nconst socket = net.connect(process.env.ALP_BRIDGE_SOCKET);\nconst waiting = new Map();\nlet sequence = 0;\nlet buffer = '';\nsocket.setEncoding('utf8');\nsocket.write(JSON.stringify({ token: process.env.ALP_BRIDGE_TOKEN }) + '\\n');\nsocket.on('data', data => {\n buffer += data;\n for (let index; (index = buffer.indexOf('\\n')) >= 0;) {\n const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);\n try { const message = JSON.parse(line); const waiter = waiting.get(message.id); if (waiter) { waiting.delete(message.id); waiter(message); } } catch {}\n }\n});\nsocket.on('close', () => process.exit(0));\nsocket.on('error', () => process.exit(1));\nconst ask = message => new Promise(resolve => { const id = ++sequence; waiting.set(id, resolve); socket.write(JSON.stringify({ ...message, id }) + '\\n'); });\nconst send = value => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...value }) + '\\n');\nreadline.createInterface({ input: process.stdin }).on('line', async line => {\n let message; try { message = JSON.parse(line); } catch { return; }\n if (message.id === undefined || message.id === null) return;\n try {\n if (message.method === 'initialize') return send({ id: message.id, result: { protocolVersion: (message.params && message.params.protocolVersion) || '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'alp', version: '1' } } });\n if (message.method === 'ping') return send({ id: message.id, result: {} });\n if (message.method === 'tools/list') { const reply = await ask({ op: 'list' }); return send({ id: message.id, result: { tools: reply.tools } }); }\n if (message.method === 'tools/call') { const reply = await ask({ op: 'call', name: message.params.name, arguments: message.params.arguments || {} }); return send({ id: message.id, result: reply.result }); }\n send({ id: message.id, error: { code: -32601, message: 'Method not found' } });\n } catch (error) { send({ id: message.id, error: { code: -32603, message: String((error && error.message) || error) } }); }\n});\nprocess.stdin.on('end', () => process.exit(0));\n";
26
+ export const ANTIGRAVITY_BRIDGE: "// ALP Antigravity bridge v1\n\nconst net = require('node:net');\nconst readline = require('node:readline');\nconst socket = process.env.ALP_BRIDGE_SOCKET ? net.connect(process.env.ALP_BRIDGE_SOCKET) : null;\nconst waiting = new Map();\nlet sequence = 0;\nlet buffer = '';\nsocket?.setEncoding('utf8');\nsocket?.write(JSON.stringify({ token: process.env.ALP_BRIDGE_TOKEN }) + '\\n');\nsocket?.on('data', data => {\n buffer += data;\n for (let index; (index = buffer.indexOf('\\n')) >= 0;) {\n const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);\n try { const message = JSON.parse(line); const waiter = waiting.get(message.id); if (waiter) { waiting.delete(message.id); waiter(message); } } catch {}\n }\n});\nsocket?.on('close', () => process.exit(0));\nsocket?.on('error', () => process.exit(1));\nconst ask = message => !socket ? Promise.resolve({ tools: [], result: { content: [{ type: 'text', text: 'No ALP session' }], isError: true } }) : new Promise(resolve => { const id = ++sequence; waiting.set(id, resolve); socket.write(JSON.stringify({ ...message, id }) + '\\n'); });\nconst send = value => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...value }) + '\\n');\nreadline.createInterface({ input: process.stdin }).on('line', async line => {\n let message; try { message = JSON.parse(line); } catch { return; }\n if (message.id === undefined || message.id === null) return;\n try {\n if (message.method === 'initialize') return send({ id: message.id, result: { protocolVersion: (message.params && message.params.protocolVersion) || '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'alp', version: '1' } } });\n if (message.method === 'ping') return send({ id: message.id, result: {} });\n if (message.method === 'tools/list') { const reply = await ask({ op: 'list' }); return send({ id: message.id, result: { tools: reply.tools } }); }\n if (message.method === 'tools/call') { const reply = await ask({ op: 'call', name: message.params.name, arguments: message.params.arguments || {} }); return send({ id: message.id, result: reply.result }); }\n send({ id: message.id, error: { code: -32601, message: 'Method not found' } });\n } catch (error) { send({ id: message.id, error: { code: -32603, message: String((error && error.message) || error) } }); }\n});\nprocess.stdin.on('end', () => process.exit(0));\n";
@@ -0,0 +1,96 @@
1
+ // packages/core/src/bridges.js
2
+ import { createRequire } from "node:module";
3
+ import { isExecutableName, nodeExecutable, stablePath } from "./packaged.js";
4
+ var ACP_BRIDGE = `
5
+ const net = require('node:net');
6
+ const readline = require('node:readline');
7
+ const socket = net.connect(process.env.ALP_BRIDGE_SOCKET);
8
+ const waiting = new Map();
9
+ let sequence = 0;
10
+ let buffer = '';
11
+ socket.setEncoding('utf8');
12
+ socket.write(JSON.stringify({ token: process.env.ALP_BRIDGE_TOKEN }) + '\\n');
13
+ socket.on('data', data => {
14
+ buffer += data;
15
+ for (let index; (index = buffer.indexOf('\\n')) >= 0;) {
16
+ const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);
17
+ try { const message = JSON.parse(line); const waiter = waiting.get(message.id); if (waiter) { waiting.delete(message.id); waiter(message); } } catch {}
18
+ }
19
+ });
20
+ socket.on('close', () => process.exit(0));
21
+ socket.on('error', () => process.exit(1));
22
+ const ask = message => new Promise(resolve => { const id = ++sequence; waiting.set(id, resolve); socket.write(JSON.stringify({ ...message, id }) + '\\n'); });
23
+ const send = value => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...value }) + '\\n');
24
+ readline.createInterface({ input: process.stdin }).on('line', async line => {
25
+ let message; try { message = JSON.parse(line); } catch { return; }
26
+ if (message.id === undefined || message.id === null) return;
27
+ try {
28
+ if (message.method === 'initialize') return send({ id: message.id, result: { protocolVersion: (message.params && message.params.protocolVersion) || '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'alp', version: '1' } } });
29
+ if (message.method === 'ping') return send({ id: message.id, result: {} });
30
+ if (message.method === 'tools/list') { const reply = await ask({ op: 'list' }); return send({ id: message.id, result: { tools: reply.tools } }); }
31
+ if (message.method === 'tools/call') { const reply = await ask({ op: 'call', name: message.params.name, arguments: message.params.arguments || {} }); return send({ id: message.id, result: reply.result }); }
32
+ send({ id: message.id, error: { code: -32601, message: 'Method not found' } });
33
+ } catch (error) { send({ id: message.id, error: { code: -32603, message: String((error && error.message) || error) } }); }
34
+ });
35
+ process.stdin.on('end', () => process.exit(0));
36
+ `;
37
+ var ANTIGRAVITY_BRIDGE = `// ALP Antigravity bridge v1
38
+
39
+ const net = require('node:net');
40
+ const readline = require('node:readline');
41
+ const socket = process.env.ALP_BRIDGE_SOCKET ? net.connect(process.env.ALP_BRIDGE_SOCKET) : null;
42
+ const waiting = new Map();
43
+ let sequence = 0;
44
+ let buffer = '';
45
+ socket?.setEncoding('utf8');
46
+ socket?.write(JSON.stringify({ token: process.env.ALP_BRIDGE_TOKEN }) + '\\n');
47
+ socket?.on('data', data => {
48
+ buffer += data;
49
+ for (let index; (index = buffer.indexOf('\\n')) >= 0;) {
50
+ const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);
51
+ try { const message = JSON.parse(line); const waiter = waiting.get(message.id); if (waiter) { waiting.delete(message.id); waiter(message); } } catch {}
52
+ }
53
+ });
54
+ socket?.on('close', () => process.exit(0));
55
+ socket?.on('error', () => process.exit(1));
56
+ const ask = message => !socket ? Promise.resolve({ tools: [], result: { content: [{ type: 'text', text: 'No ALP session' }], isError: true } }) : new Promise(resolve => { const id = ++sequence; waiting.set(id, resolve); socket.write(JSON.stringify({ ...message, id }) + '\\n'); });
57
+ const send = value => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...value }) + '\\n');
58
+ readline.createInterface({ input: process.stdin }).on('line', async line => {
59
+ let message; try { message = JSON.parse(line); } catch { return; }
60
+ if (message.id === undefined || message.id === null) return;
61
+ try {
62
+ if (message.method === 'initialize') return send({ id: message.id, result: { protocolVersion: (message.params && message.params.protocolVersion) || '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'alp', version: '1' } } });
63
+ if (message.method === 'ping') return send({ id: message.id, result: {} });
64
+ if (message.method === 'tools/list') { const reply = await ask({ op: 'list' }); return send({ id: message.id, result: { tools: reply.tools } }); }
65
+ if (message.method === 'tools/call') { const reply = await ask({ op: 'call', name: message.params.name, arguments: message.params.arguments || {} }); return send({ id: message.id, result: reply.result }); }
66
+ send({ id: message.id, error: { code: -32601, message: 'Method not found' } });
67
+ } catch (error) { send({ id: message.id, error: { code: -32603, message: String((error && error.message) || error) } }); }
68
+ });
69
+ process.stdin.on('end', () => process.exit(0));
70
+ `;
71
+ var BRIDGES = { acp: ACP_BRIDGE, antigravity: ANTIGRAVITY_BRIDGE };
72
+ function runBridge(kind) {
73
+ const source = Object.hasOwn(BRIDGES, kind) ? BRIDGES[
74
+ /** @type {'acp' | 'antigravity'} */
75
+ kind
76
+ ] : void 0;
77
+ if (!source) throw new Error(`Unknown bridge: ${kind}; expected acp or antigravity`);
78
+ new Function("require", source)(createRequire(import.meta.url));
79
+ }
80
+ function bridgeCommand(kind) {
81
+ if (!Object.hasOwn(BRIDGES, kind)) throw new Error(`Unknown bridge: ${kind}; expected acp or antigravity`);
82
+ return { command: stablePath(nodeExecutable()), args: ["-e", BRIDGES[kind]] };
83
+ }
84
+ function isBridgeArgs(kind, args, command = void 0) {
85
+ if (!Array.isArray(args)) return false;
86
+ const marker = kind === "antigravity" ? "// ALP Antigravity bridge v1" : void 0;
87
+ if (marker && args.some((arg) => typeof arg === "string" && arg.startsWith(marker))) return true;
88
+ return typeof command === "string" && isExecutableName(command) && args.length === 2 && args[0] === "bridge" && args[1] === kind;
89
+ }
90
+ export {
91
+ ACP_BRIDGE,
92
+ ANTIGRAVITY_BRIDGE,
93
+ bridgeCommand,
94
+ isBridgeArgs,
95
+ runBridge
96
+ };
@@ -0,0 +1,30 @@
1
+ /**
2
+ * The project's ledger. A missing one is empty. On read (`strict` false) an unreadable or corrupt
3
+ * one detects nothing and never blocks the task graph; a writer (`strict`) refuses it instead,
4
+ * so it never overwrites entries it could not read.
5
+ */
6
+ export function readLedger(projectRoot: any, { strict }?: {
7
+ strict?: boolean | undefined;
8
+ }): Promise<any>;
9
+ /** Records the open human gates of a task ALP just wrote (addGate, a formula's human step, a beads import) that it does not hold yet. */
10
+ export function ledgerAdopt(projectRoot: any, task: any): Promise<void>;
11
+ /**
12
+ * Records that ALP cleared or removed a human gate. Written under the task lock once every check
13
+ * passed and before the task file: should the file write fail, the gate stays open in the file.
14
+ */
15
+ export function ledgerResolve(projectRoot: any, taskId: any, gate: any, { by, channel, removed }: {
16
+ by: any;
17
+ channel: any;
18
+ removed?: boolean | undefined;
19
+ }): Promise<void>;
20
+ /**
21
+ * Reopens, in the loaded tasks, every ledgered human gate the files show cleared or
22
+ * removed without a clear in the ledger, marking it `tampered`.
23
+ */
24
+ export function applyLedger(tasks: any, ledger: any): any;
25
+ /**
26
+ * Drops the entries that no longer guard anything (t-f438): the cleared ones, which applyLedger
27
+ * skips. An open entry stays even for a closed or missing task: status and presence are file
28
+ * state an agent can edit, so only a clear ALP recorded ends an entry. Called from compaction.
29
+ */
30
+ export function ledgerPrune(projectRoot: any): Promise<number>;
@@ -0,0 +1,99 @@
1
+ // packages/core/src/gate-ledger.js
2
+ import { realpathSync } from "node:fs";
3
+ import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
4
+ import { createHash, randomUUID } from "node:crypto";
5
+ import path from "node:path";
6
+ import { alpHome } from "./library.js";
7
+ import { AlpError } from "./errors.js";
8
+ var key = (taskId, gate) => `${taskId}/${gate.id}@${gate.at}`;
9
+ function realRoot(projectRoot) {
10
+ try {
11
+ return realpathSync.native(path.resolve(projectRoot));
12
+ } catch {
13
+ return path.resolve(projectRoot);
14
+ }
15
+ }
16
+ function ledgerFile(projectRoot) {
17
+ const hash = createHash("sha256").update(realRoot(projectRoot)).digest("hex").slice(0, 24);
18
+ return path.join(alpHome(), "gates", `${hash}.json`);
19
+ }
20
+ async function readLedger(projectRoot, { strict = false } = {}) {
21
+ let data;
22
+ try {
23
+ data = JSON.parse(await readFile(ledgerFile(projectRoot), "utf8"));
24
+ } catch (error) {
25
+ if (error.code === "ENOENT") return { gates: {} };
26
+ if (strict) throw new AlpError("GATE_LEDGER_UNREADABLE", `The gate ledger ${ledgerFile(projectRoot)} is unreadable (${error.message}); fix or remove it`);
27
+ return { gates: {} };
28
+ }
29
+ if (data && typeof data === "object" && data.gates && typeof data.gates === "object") return data;
30
+ if (strict) throw new AlpError("GATE_LEDGER_UNREADABLE", `The gate ledger ${ledgerFile(projectRoot)} is not a ledger; fix or remove it`);
31
+ return { gates: {} };
32
+ }
33
+ async function writeLedger(projectRoot, ledger) {
34
+ const file = ledgerFile(projectRoot);
35
+ await mkdir(path.dirname(file), { recursive: true, mode: 448 });
36
+ const temporary = `${file}.${randomUUID().slice(0, 8)}.tmp`;
37
+ await writeFile(temporary, JSON.stringify(ledger, null, 2) + "\n", { mode: 384 });
38
+ await rename(temporary, file);
39
+ }
40
+ async function ledgerAdopt(projectRoot, task) {
41
+ const open = (task.gates ?? []).filter((gate) => gate.kind === "human" && !gate.resolved && typeof gate.at === "string" && /^g\d+$/.test(gate.id));
42
+ if (!open.length) return;
43
+ const ledger = await readLedger(projectRoot, { strict: true });
44
+ const missing = open.filter((gate) => !ledger.gates[key(task.id, gate)]);
45
+ if (!missing.length) return;
46
+ ledger.project = realRoot(projectRoot);
47
+ for (const gate of missing) ledger.gates[key(task.id, gate)] = { opened: gate.at };
48
+ await writeLedger(projectRoot, ledger);
49
+ }
50
+ async function ledgerResolve(projectRoot, taskId, gate, { by, channel, removed = false }) {
51
+ const ledger = await readLedger(projectRoot, { strict: true });
52
+ const entry = ledger.gates[key(taskId, gate)];
53
+ if (!entry) return;
54
+ entry.resolved = { at: (/* @__PURE__ */ new Date()).toISOString(), by, ...channel ? { channel } : {}, ...removed ? { removed: true } : {} };
55
+ await writeLedger(projectRoot, ledger);
56
+ }
57
+ function applyLedger(tasks, ledger) {
58
+ const byId = new Map(tasks.map((task) => [task.id, task]));
59
+ for (const [name, entry] of Object.entries(ledger.gates ?? {})) {
60
+ if (!entry || entry.resolved) continue;
61
+ const match = /^(.+)\/(g\d+)@(.+)$/.exec(name);
62
+ if (!match) continue;
63
+ const [, taskId, gateId, at] = match;
64
+ const task = byId.get(taskId);
65
+ if (!task) continue;
66
+ task.gates = Array.isArray(task.gates) ? task.gates : [];
67
+ const gate = task.gates.find((item) => item.id === gateId);
68
+ if (gate && gate.at === at && gate.kind === "human" && !gate.resolved) continue;
69
+ if (gate) {
70
+ const { resolved, ...open } = gate;
71
+ task.gates = task.gates.map((item) => item === gate ? { ...open, kind: "human", at, ...open.note ? {} : { note: "restored: this human gate was changed outside ALP" }, tampered: { at: resolved?.at ?? null, by: resolved?.by ?? null } } : item);
72
+ } else {
73
+ task.gates = [...task.gates, { id: gateId, kind: "human", note: "restored: this human gate was removed outside ALP", at, tampered: { removed: true } }];
74
+ }
75
+ if (task.step?.human && task.status === "closed") {
76
+ task.status = "open";
77
+ task.closed = null;
78
+ }
79
+ }
80
+ return tasks;
81
+ }
82
+ async function ledgerPrune(projectRoot) {
83
+ const ledger = await readLedger(projectRoot, { strict: true });
84
+ let dropped = 0;
85
+ for (const [name, entry] of Object.entries(ledger.gates)) {
86
+ if (entry && !entry.resolved) continue;
87
+ delete ledger.gates[name];
88
+ dropped += 1;
89
+ }
90
+ if (dropped) await writeLedger(projectRoot, ledger);
91
+ return dropped;
92
+ }
93
+ export {
94
+ applyLedger,
95
+ ledgerAdopt,
96
+ ledgerPrune,
97
+ ledgerResolve,
98
+ readLedger
99
+ };
package/dist/index.d.ts CHANGED
@@ -28,3 +28,4 @@ export * as user_settings from "./user-settings.js";
28
28
  export * as validation from "./validation.js";
29
29
  export * as verify from "./verify.js";
30
30
  export * as workflow from "./workflow.js";
31
+ export * as user_worktree from "./user-worktree.js";
package/dist/index.js CHANGED
@@ -29,6 +29,7 @@ import * as user_settings from "./user-settings.js";
29
29
  import * as validation from "./validation.js";
30
30
  import * as verify from "./verify.js";
31
31
  import * as workflow from "./workflow.js";
32
+ import * as user_worktree from "./user-worktree.js";
32
33
  export {
33
34
  adapter,
34
35
  atomic,
@@ -57,6 +58,7 @@ export {
57
58
  trust,
58
59
  upgrade,
59
60
  user_settings,
61
+ user_worktree,
60
62
  validation,
61
63
  verify,
62
64
  workflow
@@ -1,3 +1,11 @@
1
+ /**
2
+ * A SKILL.md with its frontmatter `name` set to `name`, so a copied or renamed skill stays valid:
3
+ * the name must equal the skill's directory. A SKILL.md without frontmatter is left as it is.
4
+ */
5
+ export function withSkillName(body: any, name: any): any;
6
+ /** Strict payload contract for opt-in project-data writes. Instructions carry prompt authority;
7
+ * executable configuration and references to it have no place in this policy. */
8
+ export function assertProjectDataContent(kind: any, content: any): void;
1
9
  /**
2
10
  * One entry: the version that applies (the project's, else the library's, else the
3
11
  * built-in), or one scope's version with `scope`. `revision` goes back with a save.
@@ -30,6 +38,31 @@ export function givenSkills(library: any, agent: any): Promise<string[]>;
30
38
  export function setGivenSkills(agent: any, skills: any, { library }?: {}): Promise<{
31
39
  skills: string[];
32
40
  }>;
41
+ /**
42
+ * The library's retired skills, newest first. `roles` is what retired.json recorded,
43
+ * or null for a skill retired before ALP wrote it.
44
+ * @returns {Promise<{ name: string, directory: string, retiredAt: string, roles: string[] | null, agent: string | null }[]>}
45
+ */
46
+ export function listRetiredSkills({ library }?: {}): Promise<{
47
+ name: string;
48
+ directory: string;
49
+ retiredAt: string;
50
+ roles: string[] | null;
51
+ agent: string | null;
52
+ }[]>;
53
+ /**
54
+ * Moves a retired skill back to <library>/skills/<name> and gives it to roles again in
55
+ * role-skills.json: `roles` when given ([] for none), else the roles retired.json recorded.
56
+ * Takes `from` when given, else the newest retired copy of the name. Refuses when the
57
+ * library already has the skill, or when neither `roles` nor retired.json says the roles.
58
+ * @returns {Promise<{ name: string, restored: string, from: string, roles: string[] }>}
59
+ */
60
+ export function restoreSkill(name: any, { library, from, roles }?: {}): Promise<{
61
+ name: string;
62
+ restored: string;
63
+ from: string;
64
+ roles: string[];
65
+ }>;
33
66
  /** Every entry of a kind with its source and users, as `alp <kind>` lists them. */
34
67
  export function listEntries(kind: any, { root, library, templates }?: {}): Promise<{
35
68
  name: string;
@@ -50,26 +83,42 @@ export function usersOf(kind: any, name: any, { root, library, templates }?: {})
50
83
  /**
51
84
  * Creates or replaces an entry in a scope. `revision` is what getEntry returned for
52
85
  * that scope (null to create); a different current revision refuses the save.
53
- * @returns {Promise<{ revision: string | null }>}
86
+ * `strict` (the CLI creating a skill): a new skill must meet the skill format; `warnings` names
87
+ * files its SKILL.md points to that are not there yet. Edits and other callers are unchanged.
88
+ * @param {string} kind
89
+ * @param {string} name
90
+ * @param {any} content
91
+ * @param {{ scope?: any, root?: string, library?: string, templates?: Record<string, string>, revision?: string | null, policy?: string, strict?: boolean }} [options]
92
+ * @returns {Promise<{ revision: string | null, warnings?: string[] }>}
54
93
  */
55
- export function saveEntry(kind: any, name: any, content: any, { scope, root, library, templates, revision }?: {}): Promise<{
94
+ export function saveEntry(kind: string, name: string, content: any, { scope, root, library, templates, revision, policy, strict }?: {
95
+ scope?: any;
96
+ root?: string;
97
+ library?: string;
98
+ templates?: Record<string, string>;
99
+ revision?: string | null;
100
+ policy?: string;
101
+ strict?: boolean;
102
+ }): Promise<{
56
103
  revision: string | null;
104
+ warnings?: string[];
57
105
  }>;
58
106
  /**
59
107
  * Removes an entry from a scope. When nothing else of that name is left below it, an
60
108
  * entry others refer to stays, and the error lists them.
61
109
  * @returns {Promise<{ removed: boolean, now?: 'builtin' | 'library' }>}
62
110
  */
63
- export function deleteEntry(kind: any, name: any, { scope, root, library, templates, revision }?: {}): Promise<{
111
+ export function deleteEntry(kind: any, name: any, { scope, root, library, templates, revision, policy }?: {}): Promise<{
64
112
  removed: boolean;
65
113
  now?: "builtin" | "library";
66
114
  }>;
67
115
  /** Copies the entry that applies under `from` to a new entry `to` in a scope; built-ins are copied this way. */
68
- export function duplicateEntry(kind: any, from: any, to: any, { scope, root, library, templates }?: {}): Promise<{
116
+ export function duplicateEntry(kind: any, from: any, to: any, { scope, root, library, templates, policy }?: {}): Promise<{
69
117
  revision: string | null;
118
+ warnings?: string[];
70
119
  }>;
71
120
  /** Renames an entry within a scope; refused while others refer to it by its old name. */
72
- export function renameEntry(kind: any, from: any, to: any, { scope, root, library, templates }?: {}): Promise<{
121
+ export function renameEntry(kind: any, from: any, to: any, { scope, root, library, templates, policy }?: {}): Promise<{
73
122
  revision: string | null;
74
123
  }>;
75
124
  /**
@@ -88,3 +137,6 @@ export function renameEntry(kind: any, from: any, to: any, { scope, root, librar
88
137
  * providers { provider } providers/<name>.json, in the library only (ALPD §46)
89
138
  */
90
139
  export const EDIT_KINDS: string[];
140
+ /** Where alp_skill_retire keeps retired skills, and the metadata file it writes in each. */
141
+ export const RETIRED_SKILLS: "retired-skills";
142
+ export const RETIRED_METADATA: "retired.json";