cairn-ai 0.1.10 → 0.2.0

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 (57) hide show
  1. package/.agents/workflows/cairn-doctor.md +2 -11
  2. package/.agents/workflows/cairn-install.md +1 -5
  3. package/.agents/workflows/cairn-memory.md +3 -1
  4. package/.agents/workflows/cairn-plan.md +6 -4
  5. package/.agents/workflows/cairn-review.md +3 -1
  6. package/.agents/workflows/cairn-toolcheck.md +2 -10
  7. package/.agents/workflows/cairn-uninstall.md +1 -11
  8. package/.agents/workflows/cairn-upgrade.md +1 -5
  9. package/.agents/workflows/cairn-work.md +4 -2
  10. package/.claude/agents/explorer.md +1 -1
  11. package/.claude/agents/worker.md +1 -1
  12. package/.claude/commands/cairn-doctor.md +1 -9
  13. package/.claude/commands/cairn-install.md +1 -5
  14. package/.claude/commands/cairn-memory.md +1 -1
  15. package/.claude/commands/cairn-plan.md +1 -1
  16. package/.claude/commands/cairn-review.md +1 -1
  17. package/.claude/commands/cairn-toolcheck.md +2 -5
  18. package/.claude/commands/cairn-uninstall.md +1 -9
  19. package/.claude/commands/cairn-upgrade.md +1 -5
  20. package/.claude/commands/cairn-work.md +1 -1
  21. package/.codex-plugin/plugin.json +6 -1
  22. package/README.de.md +5 -5
  23. package/README.es.md +5 -5
  24. package/README.fr.md +5 -5
  25. package/README.ja.md +5 -5
  26. package/README.ko.md +11 -8
  27. package/README.md +11 -8
  28. package/README.pt.md +5 -5
  29. package/README.zh.md +5 -5
  30. package/commands/cairn-doctor.md +2 -7
  31. package/commands/cairn-install.md +4 -7
  32. package/commands/cairn-memory.md +3 -3
  33. package/commands/cairn-plan.md +8 -7
  34. package/commands/cairn-review.md +3 -3
  35. package/commands/cairn-toolcheck.md +4 -6
  36. package/commands/cairn-uninstall.md +1 -7
  37. package/commands/cairn-upgrade.md +4 -7
  38. package/commands/cairn-work.md +10 -8
  39. package/docs/model-guidance/README.md +9 -6
  40. package/docs/model-guidance/claude.md +1 -1
  41. package/docs/model-guidance/codex.md +1 -1
  42. package/hooks/hooks.json +5 -5
  43. package/package.json +2 -2
  44. package/scripts/cairn-goal.mjs +539 -0
  45. package/scripts/cairn-lifecycle.mjs +140 -7
  46. package/scripts/cairn-paths.mjs +103 -0
  47. package/scripts/cairn-state.mjs +183 -131
  48. package/scripts/cairn-state.sh +68 -8
  49. package/scripts/cairn-toolcheck.mjs +312 -79
  50. package/scripts/cairn.mjs +54 -43
  51. package/skills/cairn-memory/SKILL.md +9 -3
  52. package/skills/cairn-plan/SKILL.md +26 -10
  53. package/skills/cairn-review/SKILL.md +5 -2
  54. package/skills/cairn-work/SKILL.md +34 -13
  55. package/templates/MEMORY.md +1 -1
  56. package/templates/PLAN.md +1 -0
  57. package/templates/work-plan.md +21 -4
@@ -3,10 +3,16 @@ import { createHash } from "node:crypto";
3
3
  import { realpathSync } from "node:fs";
4
4
  import { cp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
5
5
  import { homedir } from "node:os";
6
- import { dirname, join, relative, resolve } from "node:path";
6
+ import { dirname, join, posix, resolve, win32 } from "node:path";
7
7
  import { fileURLToPath, pathToFileURL } from "node:url";
8
+ import {
9
+ RUNTIME_LOCATOR_SCHEMA_VERSION,
10
+ createRuntimeLocator,
11
+ resolvePluginRoot,
12
+ runtimeRequiredPaths,
13
+ } from "./cairn-paths.mjs";
8
14
 
9
- const pluginRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
15
+ const pluginRoot = resolvePluginRoot(import.meta.url);
10
16
  const homeRoot = process.env.HOME ?? process.env.USERPROFILE ?? homedir() ?? ".";
11
17
  const codexHome = resolve(process.env.CODEX_HOME ?? join(homeRoot, ".codex"));
12
18
  const claudeHome = resolve(process.env.CLAUDE_HOME ?? join(homeRoot, ".claude"));
@@ -18,6 +24,8 @@ const pluginName = "cairn";
18
24
  const marketplaceRoot = join(codexHome, "plugins", "cache", marketplaceName);
19
25
  const installedPluginRoot = join(marketplaceRoot, "plugins", pluginName);
20
26
  const marketplaceJsonPath = join(marketplaceRoot, ".agents", "plugins", "marketplace.json");
27
+ const installedRuntimeLocatorPath = join(installedPluginRoot, ".cairn-runtime.json");
28
+ const claudeRuntimeLocatorPath = join(claudeHome, "cairn", "runtime.json");
21
29
 
22
30
  if (isCliEntry()) {
23
31
  const command = process.argv[2] ?? "help";
@@ -28,7 +36,12 @@ if (isCliEntry()) {
28
36
  }
29
37
 
30
38
  async function install(mode) {
39
+ if (samePath(pluginRoot, installedPluginRoot)) {
40
+ throw new Error("Run install or upgrade from the Cairn package/global source, not from the installed cache.");
41
+ }
31
42
  await copyPlugin();
43
+ await writeRuntimeLocator(installedRuntimeLocatorPath);
44
+ await writeInstalledSkillLocators();
32
45
  await writeMarketplace();
33
46
  await installClaudeFiles();
34
47
  await installAntigravityFiles();
@@ -51,6 +64,11 @@ async function doctor() {
51
64
  const installedManifest = await readJson(join(installedPluginRoot, ".codex-plugin", "plugin.json"));
52
65
  checks.push(["installed hooks manifest field", installedManifest?.hooks === "./hooks/hooks.json"]);
53
66
  checks.push(["hooks file", await exists(join(installedPluginRoot, "hooks", "hooks.json"))]);
67
+ checks.push(["installed runtime locator", await validRuntimeLocator(installedRuntimeLocatorPath)]);
68
+ checks.push(["installed skill locators", (await Promise.all(skillNames().map((name) => validRuntimeLocator(installedSkillLocatorPath(name))))).every(Boolean)]);
69
+ checks.push(["installed CLI script", await exists(join(installedPluginRoot, "scripts", "cairn.mjs"))]);
70
+ checks.push(["installed plan template", await exists(join(installedPluginRoot, "templates", "work-plan.md"))]);
71
+ checks.push(["installed model guidance", await exists(join(installedPluginRoot, "docs", "model-guidance", "codex.md"))]);
54
72
  const config = await readText(configPath);
55
73
  checks.push(["config features.plugins", hasSetting(config, "features", "plugins", "true")]);
56
74
  checks.push(["config features.plugin_hooks", hasSetting(config, "features", "plugin_hooks", "true")]);
@@ -63,10 +81,15 @@ async function doctor() {
63
81
  checks.push(["trusted hook states", expectedStates.length > 0 && missingStates.length === 0]);
64
82
  checks.push(["Claude commands", await exists(join(claudeHome, "commands", "cairn-plan.md"))]);
65
83
  checks.push(["Claude agents", await exists(join(claudeHome, "agents", "cairn-explorer.md"))]);
84
+ checks.push(["Claude runtime locator", await validRuntimeLocator(claudeRuntimeLocatorPath)]);
66
85
  checks.push(["Antigravity skills", await exists(join(antigravityHome, "skills", "cairn-plan", "SKILL.md"))]);
67
86
  checks.push(["Antigravity workflows", await exists(join(antigravityHome, "workflows", "cairn-plan.md"))]);
87
+ checks.push(["Antigravity runtime locator", await validRuntimeLocator(antigravityRuntimeLocatorPath(antigravityHome))]);
88
+ checks.push(["Antigravity skill locators", (await Promise.all(skillNames().map((name) => validRuntimeLocator(antigravitySkillLocatorPath(antigravityHome, name))))).every(Boolean)]);
68
89
  checks.push(["Antigravity CLI skills", await exists(join(antigravityCliHome, "skills", "cairn-plan", "SKILL.md"))]);
69
90
  checks.push(["Antigravity CLI workflows", await exists(join(antigravityCliHome, "workflows", "cairn-plan.md"))]);
91
+ checks.push(["Antigravity CLI runtime locator", await validRuntimeLocator(antigravityRuntimeLocatorPath(antigravityCliHome))]);
92
+ checks.push(["Antigravity CLI skill locators", (await Promise.all(skillNames().map((name) => validRuntimeLocator(antigravitySkillLocatorPath(antigravityCliHome, name))))).every(Boolean)]);
70
93
  for (const [name, ok] of checks) console.log(`${ok ? "OK" : "FAIL"} ${name}`);
71
94
  if (checks.some(([, ok]) => !ok)) process.exitCode = 1;
72
95
  }
@@ -82,6 +105,7 @@ async function uninstall() {
82
105
  for (const name of ["architect", "planner", "builder", "reviewer", "explorer", "worker"]) {
83
106
  await rm(join(claudeHome, "agents", `cairn-${name}.md`), { force: true });
84
107
  }
108
+ await rm(join(claudeHome, "cairn"), { recursive: true, force: true });
85
109
  await uninstallAntigravityFiles();
86
110
  console.log(t("uninstallComplete"));
87
111
  }
@@ -91,7 +115,7 @@ async function copyPlugin() {
91
115
  await mkdir(dirname(installedPluginRoot), { recursive: true });
92
116
  await cp(pluginRoot, installedPluginRoot, {
93
117
  recursive: true,
94
- filter: (source) => !pathHasSegment(relative(pluginRoot, source), ".git") && !pathHasSegment(relative(pluginRoot, source), "node_modules"),
118
+ filter: shouldCopyPluginPath,
95
119
  });
96
120
  const manifestPath = join(installedPluginRoot, ".codex-plugin", "plugin.json");
97
121
  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
@@ -117,11 +141,20 @@ async function writeMarketplace() {
117
141
  async function installClaudeFiles() {
118
142
  await mkdir(join(claudeHome, "commands"), { recursive: true });
119
143
  await mkdir(join(claudeHome, "agents"), { recursive: true });
144
+ await writeRuntimeLocator(claudeRuntimeLocatorPath);
120
145
  for (const name of commandNames()) {
121
- await cp(join(pluginRoot, ".claude", "commands", `cairn-${name}.md`), join(claudeHome, "commands", `cairn-${name}.md`));
146
+ await renderMirrorFile(
147
+ join(installedPluginRoot, ".claude", "commands", `cairn-${name}.md`),
148
+ join(claudeHome, "commands", `cairn-${name}.md`),
149
+ claudeRuntimeLocatorPath,
150
+ );
122
151
  }
123
152
  for (const name of ["explorer", "worker"]) {
124
- await cp(join(pluginRoot, ".claude", "agents", `${name}.md`), join(claudeHome, "agents", `cairn-${name}.md`));
153
+ await renderMirrorFile(
154
+ join(installedPluginRoot, ".claude", "agents", `${name}.md`),
155
+ join(claudeHome, "agents", `cairn-${name}.md`),
156
+ claudeRuntimeLocatorPath,
157
+ );
125
158
  }
126
159
  }
127
160
 
@@ -129,12 +162,24 @@ async function installAntigravityFiles() {
129
162
  for (const root of [antigravityHome, antigravityCliHome]) {
130
163
  await mkdir(join(root, "skills"), { recursive: true });
131
164
  await mkdir(join(root, "workflows"), { recursive: true });
165
+ await writeRuntimeLocator(antigravityRuntimeLocatorPath(root));
132
166
  for (const name of skillNames()) {
133
167
  await rm(join(root, "skills", name), { recursive: true, force: true });
134
- await cp(join(pluginRoot, "skills", name), join(root, "skills", name), { recursive: true });
168
+ await cp(join(installedPluginRoot, "skills", name), join(root, "skills", name), { recursive: true });
169
+ await renderMirrorFile(
170
+ join(installedPluginRoot, "skills", name, "SKILL.md"),
171
+ join(root, "skills", name, "SKILL.md"),
172
+ antigravitySkillLocatorPath(root, name),
173
+ { includeLocatorNotice: true },
174
+ );
175
+ await writeRuntimeLocator(antigravitySkillLocatorPath(root, name));
135
176
  }
136
177
  for (const name of commandNames()) {
137
- await cp(join(pluginRoot, ".agents", "workflows", `cairn-${name}.md`), join(root, "workflows", `cairn-${name}.md`));
178
+ await renderMirrorFile(
179
+ join(installedPluginRoot, ".agents", "workflows", `cairn-${name}.md`),
180
+ join(root, "workflows", `cairn-${name}.md`),
181
+ antigravityRuntimeLocatorPath(root),
182
+ );
138
183
  }
139
184
  }
140
185
  }
@@ -147,6 +192,7 @@ async function uninstallAntigravityFiles() {
147
192
  for (const name of commandNames()) {
148
193
  await rm(join(root, "workflows", `cairn-${name}.md`), { force: true });
149
194
  }
195
+ await rm(join(root, "cairn"), { recursive: true, force: true });
150
196
  }
151
197
  }
152
198
 
@@ -267,6 +313,19 @@ export function pathHasSegment(path, segment) {
267
313
  return path.split(/[\\/]+/).includes(segment);
268
314
  }
269
315
 
316
+ export function shouldCopyPluginPath(source) {
317
+ const name = source.split(/[\\/]+/).at(-1);
318
+ return name !== ".git" && name !== "node_modules";
319
+ }
320
+
321
+ export function samePath(left, right) {
322
+ try {
323
+ return realpathSync(left) === realpathSync(right);
324
+ } catch {
325
+ return resolve(left) === resolve(right);
326
+ }
327
+ }
328
+
270
329
  export function commandNames() {
271
330
  return ["install", "upgrade", "doctor", "uninstall", "memory", "plan", "work", "review", "toolcheck"];
272
331
  }
@@ -275,6 +334,80 @@ export function skillNames() {
275
334
  return ["cairn-memory", "cairn-plan", "cairn-work", "cairn-review"];
276
335
  }
277
336
 
337
+ export function renderInstalledMirror(content, {
338
+ runtimeRoot = installedPluginRoot,
339
+ locatorPath = installedRuntimeLocatorPath,
340
+ platform = process.platform,
341
+ } = {}) {
342
+ const platformJoin = platform === "win32" ? win32.join : posix.join;
343
+ const quotedCli = quoteShellArg(platformJoin(runtimeRoot, "scripts", "cairn.mjs"), platform);
344
+ let rendered = content
345
+ .replaceAll("{{CAIRN_RUNTIME_LOCATOR_JSON}}", JSON.stringify(locatorPath))
346
+ .replace(/\bnode\s+scripts\/cairn\.mjs\b/g, `node ${quotedCli}`)
347
+ .replace(/\bnode\s+scripts\/([A-Za-z0-9._/-]+)/g, (_, path) => `node ${quoteShellArg(join(runtimeRoot, "scripts", path), platform)}`);
348
+
349
+ rendered = rendered.replace(
350
+ /(^|[\s`("'=])(commands|agents|templates|docs\/model-guidance)\/([A-Za-z0-9._<>/-]+)/gm,
351
+ (_, prefix, directory, suffix) => `${prefix}${platformJoin(runtimeRoot, directory, suffix)}`,
352
+ );
353
+ return rendered;
354
+ }
355
+
356
+ export function quoteShellArg(value, platform = process.platform) {
357
+ if (platform === "win32") return `"${value.replaceAll('"', '""')}"`;
358
+ return `'${value.replaceAll("'", "'\\''")}'`;
359
+ }
360
+
361
+ function antigravityRuntimeLocatorPath(root) {
362
+ return join(root, "cairn", "runtime.json");
363
+ }
364
+
365
+ function installedSkillLocatorPath(skillName) {
366
+ return join(installedPluginRoot, "skills", skillName, "references", "cairn-runtime.json");
367
+ }
368
+
369
+ function antigravitySkillLocatorPath(root, skillName) {
370
+ return join(root, "skills", skillName, "references", "cairn-runtime.json");
371
+ }
372
+
373
+ async function writeRuntimeLocator(path) {
374
+ await mkdir(dirname(path), { recursive: true });
375
+ await writeFile(path, `${JSON.stringify(createRuntimeLocator(installedPluginRoot), null, 2)}\n`);
376
+ }
377
+
378
+ async function writeInstalledSkillLocators() {
379
+ await Promise.all(skillNames().map((name) => writeRuntimeLocator(installedSkillLocatorPath(name))));
380
+ }
381
+
382
+ async function validRuntimeLocator(path) {
383
+ try {
384
+ const locator = await readJson(path);
385
+ const expected = createRuntimeLocator(installedPluginRoot);
386
+ if (locator?.schemaVersion !== RUNTIME_LOCATOR_SCHEMA_VERSION) return false;
387
+ if (resolve(locator.pluginRoot ?? ".") !== resolve(installedPluginRoot)) return false;
388
+ for (const [name, expectedPath] of Object.entries(expected.entrypoints)) {
389
+ if (locator.entrypoints?.[name] !== expectedPath) return false;
390
+ }
391
+ for (const [name, expectedPath] of Object.entries(expected.resources)) {
392
+ if (locator.resources?.[name] !== expectedPath) return false;
393
+ }
394
+ const requiredPaths = runtimeRequiredPaths(locator);
395
+ if (requiredPaths.length === 0) return false;
396
+ return (await Promise.all(requiredPaths.map(exists))).every(Boolean);
397
+ } catch {
398
+ return false;
399
+ }
400
+ }
401
+
402
+ async function renderMirrorFile(source, destination, locatorPath, { includeLocatorNotice = false } = {}) {
403
+ const content = await readFile(source, "utf8");
404
+ const notice = includeLocatorNotice
405
+ ? `\n\n## Installed Cairn runtime\n\nRead the structured runtime locator at \`${JSON.stringify(locatorPath)}\`. Resolve Cairn scripts and static resources from its absolute paths, never from the target project.\n`
406
+ : "";
407
+ await mkdir(dirname(destination), { recursive: true });
408
+ await writeFile(destination, `${renderInstalledMirror(content, { runtimeRoot: installedPluginRoot, locatorPath }).trimEnd()}${notice}`);
409
+ }
410
+
278
411
  function help() {
279
412
  console.log(t("usage"));
280
413
  }
@@ -0,0 +1,103 @@
1
+ import { existsSync } from "node:fs";
2
+ import { dirname, join, resolve } from "node:path";
3
+ import { fileURLToPath } from "node:url";
4
+
5
+ export const RUNTIME_LOCATOR_SCHEMA_VERSION = 1;
6
+
7
+ export function resolvePluginRoot(moduleUrl = import.meta.url) {
8
+ return resolve(dirname(fileURLToPath(moduleUrl)), "..");
9
+ }
10
+
11
+ export function parseRootArgs(args = [], options = {}) {
12
+ const remaining = [];
13
+ let explicitRoot = null;
14
+
15
+ for (let index = 0; index < args.length; index += 1) {
16
+ const argument = args[index];
17
+ if (argument === "--root") {
18
+ if (explicitRoot !== null) throw new Error("--root may only be provided once");
19
+ const value = args[index + 1];
20
+ if (!value || value.startsWith("--")) throw new Error("--root requires a path");
21
+ explicitRoot = value;
22
+ index += 1;
23
+ continue;
24
+ }
25
+ if (argument.startsWith("--root=")) {
26
+ if (explicitRoot !== null) throw new Error("--root may only be provided once");
27
+ const value = argument.slice("--root=".length);
28
+ if (!value) throw new Error("--root requires a path");
29
+ explicitRoot = value;
30
+ continue;
31
+ }
32
+ remaining.push(argument);
33
+ }
34
+
35
+ return {
36
+ args: remaining,
37
+ explicitRoot,
38
+ repoRoot: resolveRepoRoot({ ...options, explicitRoot }),
39
+ };
40
+ }
41
+
42
+ export function resolveRepoRoot({
43
+ explicitRoot = null,
44
+ hookCwd = null,
45
+ cwd = process.cwd(),
46
+ env = process.env,
47
+ } = {}) {
48
+ if (explicitRoot) return resolve(cwd, explicitRoot);
49
+ if (hookCwd) {
50
+ const hookStart = resolve(hookCwd);
51
+ return discoverRepositoryRoot(hookStart) ?? hookStart;
52
+ }
53
+ if (env.HARNESS_REPO_ROOT) return resolve(env.HARNESS_REPO_ROOT);
54
+ const start = resolve(cwd);
55
+ return discoverRepositoryRoot(start) ?? start;
56
+ }
57
+
58
+ export function discoverRepositoryRoot(start = process.cwd()) {
59
+ let current = resolve(start);
60
+ while (true) {
61
+ if (existsSync(join(current, ".git"))) return current;
62
+ const parent = dirname(current);
63
+ if (parent === current) return null;
64
+ current = parent;
65
+ }
66
+ }
67
+
68
+ export function createRuntimeLocator(pluginRoot) {
69
+ const root = resolve(pluginRoot);
70
+ return {
71
+ schemaVersion: RUNTIME_LOCATOR_SCHEMA_VERSION,
72
+ plugin: "cairn",
73
+ pluginRoot: root,
74
+ entrypoints: {
75
+ cli: join(root, "scripts", "cairn.mjs"),
76
+ lifecycle: join(root, "scripts", "cairn-lifecycle.mjs"),
77
+ state: join(root, "scripts", "cairn-state.mjs"),
78
+ toolcheck: join(root, "scripts", "cairn-toolcheck.mjs"),
79
+ },
80
+ resources: {
81
+ agents: join(root, "agents"),
82
+ commands: join(root, "commands"),
83
+ modelGuidance: join(root, "docs", "model-guidance"),
84
+ skills: join(root, "skills"),
85
+ templates: join(root, "templates"),
86
+ },
87
+ };
88
+ }
89
+
90
+ export function runtimeRequiredPaths(locator) {
91
+ if (!locator || locator.schemaVersion !== RUNTIME_LOCATOR_SCHEMA_VERSION || locator.plugin !== "cairn") return [];
92
+ return [
93
+ locator.entrypoints?.cli,
94
+ locator.entrypoints?.state,
95
+ locator.entrypoints?.toolcheck,
96
+ locator.resources?.commands,
97
+ locator.resources?.agents,
98
+ locator.resources?.skills,
99
+ join(locator.resources?.templates ?? "", "work-plan.md"),
100
+ join(locator.resources?.modelGuidance ?? "", "README.md"),
101
+ join(locator.resources?.modelGuidance ?? "", "codex.md"),
102
+ ].filter(Boolean);
103
+ }