@ardenthq/airc 0.1.0 → 0.1.1

package/dist/cli.js

@@ -0,0 +1,546 @@
+#!/usr/bin/env node
+
+// src/run.ts
+import { parseArgs } from "util";
+
+// src/guidelines-repository.ts
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { fileURLToPath } from "url";
+import { join } from "path";
+import { parse } from "yaml";
+var GuidelinesRepository = class _GuidelinesRepository {
+  constructor(guidelinesPath, version = "dev") {
+    this.guidelinesPath = guidelinesPath;
+    this.version = version;
+    if (!existsSync(guidelinesPath) || !statSync(guidelinesPath).isDirectory()) {
+      throw new Error(`Guidelines directory not found: ${guidelinesPath}`);
+    }
+  }
+  guidelinesPath;
+  version;
+  /** Resolve the guidelines directory bundled with the package. */
+  static default() {
+    return new _GuidelinesRepository(
+      fileURLToPath(new URL("../guidelines", import.meta.url)),
+      readPackageVersion()
+    );
+  }
+  /** Guideline names without extension, sorted, e.g. ["core", "js", "php"]. */
+  names() {
+    return readdirSync(this.guidelinesPath).filter((file) => file.endsWith(".md")).map((file) => file.slice(0, -".md".length)).sort();
+  }
+  has(name) {
+    return existsSync(this.path(name));
+  }
+  read(name) {
+    if (!this.has(name)) {
+      throw new Error(`Guideline not found: ${name}`);
+    }
+    return readFileSync(this.path(name), "utf8").replaceAll("{{VERSION}}", this.version);
+  }
+  path(name) {
+    return join(this.guidelinesPath, `${name}.md`);
+  }
+  recommendations() {
+    const file = join(this.guidelinesPath, "recommended.yaml");
+    if (!existsSync(file)) {
+      return { skills: [], composer: [], npm: [] };
+    }
+    const parsed = parse(readFileSync(file, "utf8")) ?? {};
+    return {
+      skills: parsed.skills ?? [],
+      composer: parsed.composer ?? [],
+      npm: parsed.npm ?? []
+    };
+  }
+};
+function readPackageVersion() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8")
+    );
+    return typeof pkg.version === "string" ? pkg.version : "dev";
+  } catch {
+    return "dev";
+  }
+}
+
+// src/claude-md-editor.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { join as join2 } from "path";
+var ClaudeMdEditor = class _ClaudeMdEditor {
+  constructor(repoPath) {
+    this.repoPath = repoPath;
+  }
+  repoPath;
+  static POINTER = "<!-- Project-specific instructions go below. -->";
+  path() {
+    return join2(this.repoPath, "CLAUDE.md");
+  }
+  exists() {
+    return existsSync2(this.path());
+  }
+  importLine(name) {
+    return `@.claude/ardenthq/${name}.md`;
+  }
+  /** Ensure an import exists for each guideline. Returns the names newly added. */
+  ensureImports(names) {
+    if (!this.exists()) {
+      this.create(names);
+      return names;
+    }
+    const contents = readFileSync2(this.path(), "utf8");
+    const missing = names.filter((name) => !this.hasImport(contents, name));
+    if (missing.length === 0) {
+      return [];
+    }
+    const block = missing.map((name) => this.importLine(name)).join("\n");
+    writeFileSync(this.path(), `${block}
+${contents}`);
+    return missing;
+  }
+  /** Names whose import line is absent (all of them when CLAUDE.md is missing). */
+  missingImports(names) {
+    if (!this.exists()) {
+      return names;
+    }
+    const contents = readFileSync2(this.path(), "utf8");
+    return names.filter((name) => !this.hasImport(contents, name));
+  }
+  hasImport(contents, name) {
+    const line = this.importLine(name);
+    return contents.split(/\r?\n/).some((row) => row.trim() === line);
+  }
+  create(names) {
+    const imports = names.map((name) => this.importLine(name)).join("\n");
+    writeFileSync(this.path(), `${imports}
+
+${_ClaudeMdEditor.POINTER}
+`);
+  }
+};
+
+// src/gitignore-editor.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { join as join3 } from "path";
+var GitignoreEditor = class _GitignoreEditor {
+  constructor(repoPath) {
+    this.repoPath = repoPath;
+  }
+  repoPath;
+  static HEADER = "# airc";
+  path() {
+    return join3(this.repoPath, ".gitignore");
+  }
+  /** Add the entry if missing. Returns true when the file was modified. */
+  ensure(entry) {
+    if (!existsSync3(this.path())) {
+      writeFileSync2(this.path(), `${_GitignoreEditor.HEADER}
+${entry}
+`);
+      return true;
+    }
+    const contents = readFileSync3(this.path(), "utf8");
+    if (this.has(contents, entry)) {
+      return false;
+    }
+    const separator = contents === "" || contents.endsWith("\n") ? "" : "\n";
+    writeFileSync2(this.path(), `${contents}${separator}
+${_GitignoreEditor.HEADER}
+${entry}
+`);
+    return true;
+  }
+  has(contents, entry) {
+    return contents.split(/\r?\n/).some((row) => row.trim() === entry);
+  }
+};
+
+// src/guideline-selector.ts
+var GuidelineSelector = class _GuidelineSelector {
+  constructor(guidelines) {
+    this.guidelines = guidelines;
+  }
+  guidelines;
+  static STACK_GUIDELINES = {
+    php: ["php"],
+    js: ["js"]
+  };
+  /** Guideline names that exist, `core` first. */
+  for(stacks) {
+    const selected = ["core"];
+    for (const stack of stacks) {
+      selected.push(..._GuidelineSelector.STACK_GUIDELINES[stack] ?? []);
+    }
+    return [...new Set(selected)].filter((name) => this.guidelines.has(name));
+  }
+};
+
+// src/guideline-writer.ts
+import { existsSync as existsSync4, mkdirSync, readFileSync as readFileSync4, readdirSync as readdirSync2, writeFileSync as writeFileSync3 } from "fs";
+import { basename, join as join4 } from "path";
+var GuidelineWriter = class _GuidelineWriter {
+  constructor(guidelines, repoPath) {
+    this.guidelines = guidelines;
+    this.repoPath = repoPath;
+  }
+  guidelines;
+  repoPath;
+  static RELATIVE_DIR = ".claude/ardenthq";
+  directory() {
+    return join4(this.repoPath, _GuidelineWriter.RELATIVE_DIR);
+  }
+  write(names) {
+    mkdirSync(this.directory(), { recursive: true });
+    const result2 = { created: [], updated: [], unchanged: [], stale: [] };
+    for (const name of names) {
+      result2[this.writeOne(name)].push(name);
+    }
+    result2.stale = this.staleFiles(names);
+    return result2;
+  }
+  /** Read-only comparison of selected guidelines against what's on disk. */
+  diff(names) {
+    const missing = [];
+    const outdated = [];
+    for (const name of names) {
+      const target = join4(this.directory(), `${name}.md`);
+      if (!existsSync4(target)) {
+        missing.push(name);
+      } else if (readFileSync4(target, "utf8") !== this.guidelines.read(name)) {
+        outdated.push(name);
+      }
+    }
+    return { missing, outdated };
+  }
+  writeOne(name) {
+    const target = join4(this.directory(), `${name}.md`);
+    const contents = this.guidelines.read(name);
+    if (!existsSync4(target)) {
+      writeFileSync3(target, contents);
+      return "created";
+    }
+    if (readFileSync4(target, "utf8") === contents) {
+      return "unchanged";
+    }
+    writeFileSync3(target, contents);
+    return "updated";
+  }
+  staleFiles(written) {
+    return readdirSync2(this.directory()).filter((file) => file.endsWith(".md")).map((file) => basename(file, ".md")).filter((name) => !written.includes(name)).sort();
+  }
+};
+
+// src/recommendations.ts
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
+import { homedir } from "os";
+import { join as join5 } from "path";
+var CHANNELS = ["skills", "composer", "npm"];
+var Recommendations = class {
+  constructor(guidelines, repoPath) {
+    this.guidelines = guidelines;
+    this.repoPath = repoPath;
+  }
+  guidelines;
+  repoPath;
+  for(stacks) {
+    const all = this.guidelines.recommendations();
+    const result2 = { skills: [], composer: [], npm: [] };
+    for (const channel of CHANNELS) {
+      result2[channel] = all[channel].filter((entry) => this.shouldSuggest(entry, stacks));
+    }
+    return result2;
+  }
+  flat(stacks) {
+    const grouped = this.for(stacks);
+    return [...grouped.skills, ...grouped.composer, ...grouped.npm];
+  }
+  shouldSuggest(entry, stacks) {
+    return this.matchesStacks(entry, stacks) && !this.isInstalled(entry);
+  }
+  matchesStacks(entry, stacks) {
+    const required = entry.stacks ?? [];
+    return required.length === 0 || required.some((stack) => stacks.includes(stack));
+  }
+  isInstalled(entry) {
+    const detect = entry.detect;
+    if (!detect) {
+      return false;
+    }
+    if (detect.paths && this.anyPathExists(toList(detect.paths))) {
+      return true;
+    }
+    if (detect.composerJson && this.manifestHas("composer.json", toList(detect.composerJson))) {
+      return true;
+    }
+    return Boolean(detect.npmJson) && this.manifestHas("package.json", toList(detect.npmJson));
+  }
+  anyPathExists(paths) {
+    return paths.some((path) => existsSync5(expandHome(path)));
+  }
+  manifestHas(file, packages) {
+    const path = join5(this.repoPath, file);
+    if (!existsSync5(path)) {
+      return false;
+    }
+    let manifest;
+    try {
+      manifest = JSON.parse(readFileSync5(path, "utf8"));
+    } catch {
+      return false;
+    }
+    const installed = /* @__PURE__ */ new Set();
+    for (const section of ["require", "require-dev", "dependencies", "devDependencies"]) {
+      const deps = manifest[section];
+      if (typeof deps === "object" && deps !== null) {
+        for (const name of Object.keys(deps)) {
+          installed.add(name);
+        }
+      }
+    }
+    return packages.some((pkg) => installed.has(pkg));
+  }
+};
+function toList(value) {
+  if (typeof value === "string") {
+    return [value];
+  }
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function expandHome(path) {
+  if (!path.startsWith("~/")) {
+    return path;
+  }
+  return join5(process.env.HOME ?? homedir(), path.slice(2));
+}
+
+// src/stack-detector.ts
+import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
+import { join as join6 } from "path";
+var StackDetector = class {
+  constructor(repoPath) {
+    this.repoPath = repoPath;
+  }
+  repoPath;
+  /** e.g. ["php", "laravel"] or ["js"]. */
+  stacks() {
+    return [...this.phpStacks(), ...this.jsStacks()];
+  }
+  has(stack) {
+    return this.stacks().includes(stack);
+  }
+  phpStacks() {
+    const composer = this.readJson("composer.json");
+    if (composer === null) {
+      return [];
+    }
+    const stacks = ["php"];
+    if (this.requires(composer, "laravel/framework")) {
+      stacks.push("laravel");
+    }
+    return stacks;
+  }
+  jsStacks() {
+    return this.readJson("package.json") === null ? [] : ["js"];
+  }
+  requires(manifest, pkg) {
+    return ["require", "require-dev", "dependencies", "devDependencies"].some((section) => {
+      const deps = manifest[section];
+      return typeof deps === "object" && deps !== null && pkg in deps;
+    });
+  }
+  readJson(file) {
+    const path = join6(this.repoPath, file);
+    if (!existsSync6(path)) {
+      return null;
+    }
+    try {
+      const parsed = JSON.parse(readFileSync6(path, "utf8"));
+      return typeof parsed === "object" && parsed !== null ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/installer.ts
+var NO_RECOMMENDATIONS = { skills: [], composer: [], npm: [] };
+var Installer = class {
+  detector;
+  selector;
+  writer;
+  claudeMd;
+  gitignore;
+  recommendations;
+  constructor(guidelines, repoPath) {
+    this.detector = new StackDetector(repoPath);
+    this.selector = new GuidelineSelector(guidelines);
+    this.writer = new GuidelineWriter(guidelines, repoPath);
+    this.claudeMd = new ClaudeMdEditor(repoPath);
+    this.gitignore = new GitignoreEditor(repoPath);
+    this.recommendations = new Recommendations(guidelines, repoPath);
+  }
+  install(manageGitignore = true) {
+    const stacks = this.detector.stacks();
+    const names = this.selector.for(stacks);
+    const guidelines = this.writer.write(names);
+    const claudeMdExisted = this.claudeMd.exists();
+    const importsAdded = this.claudeMd.ensureImports(names);
+    const gitignoreModified = manageGitignore && this.gitignore.ensure("CLAUDE.local.md");
+    return {
+      stacks,
+      guidelines,
+      importsAdded,
+      claudeMdCreated: !claudeMdExisted,
+      gitignoreModified,
+      recommendations: this.recommendations.for(stacks)
+    };
+  }
+  /** Read-only drift check, for CI. Reports what install/update would change. */
+  check() {
+    const stacks = this.detector.stacks();
+    const names = this.selector.for(stacks);
+    const { missing, outdated } = this.writer.diff(names);
+    const missingImports = this.claudeMd.missingImports(names);
+    return {
+      stacks,
+      missing,
+      outdated,
+      missingImports,
+      inSync: missing.length === 0 && outdated.length === 0 && missingImports.length === 0
+    };
+  }
+  /** Recurring sync. Rewrites managed guideline files only. */
+  update() {
+    const stacks = this.detector.stacks();
+    const names = this.selector.for(stacks);
+    return {
+      stacks,
+      guidelines: this.writer.write(names),
+      importsAdded: [],
+      claudeMdCreated: false,
+      gitignoreModified: false,
+      recommendations: NO_RECOMMENDATIONS
+    };
+  }
+};
+function flatRecommendations(result2) {
+  return [
+    ...result2.recommendations.skills,
+    ...result2.recommendations.composer,
+    ...result2.recommendations.npm
+  ];
+}
+
+// src/output-renderer.ts
+function render(result2, showRecommendations = true) {
+  const lines = [...summary(result2), ...showRecommendations ? recommendations(result2) : []];
+  return `${lines.join("\n")}
+`;
+}
+function renderCheck(result2) {
+  if (result2.inSync) {
+    return "\u2713 airc: guidelines in sync\n";
+  }
+  const lines = ["\u2717 airc: out of sync"];
+  if (result2.missing.length > 0) {
+    lines.push(`  missing: ${fileList(result2.missing)}`);
+  }
+  if (result2.outdated.length > 0) {
+    lines.push(`  outdated: ${fileList(result2.outdated)}`);
+  }
+  if (result2.missingImports.length > 0) {
+    lines.push(`  missing imports: ${result2.missingImports.join(", ")}`);
+  }
+  lines.push("", "Run `npx @ardenthq/airc install` to fix.");
+  return `${lines.join("\n")}
+`;
+}
+function summary(result2) {
+  const lines = ["\u2713 airc"];
+  const written = [...result2.guidelines.created, ...result2.guidelines.updated];
+  if (written.length > 0) {
+    lines.push(`  wrote ${fileList(written)}`);
+  } else if (result2.guidelines.unchanged.length > 0) {
+    lines.push(`  up to date (${fileList(result2.guidelines.unchanged)})`);
+  }
+  if (result2.claudeMdCreated) {
+    lines.push("  created CLAUDE.md with imports");
+  } else if (result2.importsAdded.length > 0) {
+    lines.push(`  added ${result2.importsAdded.length} import(s) to CLAUDE.md`);
+  }
+  if (result2.gitignoreModified) {
+    lines.push("  added CLAUDE.local.md to .gitignore");
+  }
+  if (result2.guidelines.stale.length > 0) {
+    lines.push(`  stale (no longer selected, not removed): ${fileList(result2.guidelines.stale)}`);
+  }
+  return lines;
+}
+function recommendations(result2) {
+  const entries = flatRecommendations(result2);
+  if (entries.length === 0) {
+    return [];
+  }
+  const lines = ["", "Recommended (not yet installed):"];
+  for (const entry of entries) {
+    lines.push(`  ${entry.name}${entry.description ? ` \u2014 ${entry.description}` : ""}`);
+    if (entry.install) {
+      lines.push(`    ${entry.install}`);
+    }
+  }
+  lines.push("", "Skip recommendations: export AIRC_QUIET=1");
+  return lines;
+}
+function fileList(names) {
+  return names.map((name) => `${name}.md`).join(", ");
+}
+
+// src/run.ts
+var USAGE = `airc \u2014 shared Claude conventions
+
+Usage:
+  airc install [--path <dir>] [--no-gitignore]
+  airc update  [--path <dir>]
+  airc check   [--path <dir>]
+`;
+function run(argv, options = {}) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        path: { type: "string" },
+        "no-gitignore": { type: "boolean", default: false }
+      }
+    });
+  } catch (error) {
+    return { code: 1, stdout: `${error.message}
+
+${USAGE}` };
+  }
+  const command = parsed.positionals[0];
+  const repoPath = parsed.values.path ?? options.cwd ?? process.cwd();
+  const guidelines = options.guidelines ?? GuidelinesRepository.default();
+  const installer = new Installer(guidelines, repoPath);
+  if (command === "install") {
+    const result2 = installer.install(!parsed.values["no-gitignore"]);
+    return { code: 0, stdout: render(result2, !options.quiet) };
+  }
+  if (command === "update") {
+    return { code: 0, stdout: render(installer.update(), false) };
+  }
+  if (command === "check") {
+    const result2 = installer.check();
+    return { code: result2.inSync ? 0 : 1, stdout: renderCheck(result2) };
+  }
+  return { code: command ? 1 : 0, stdout: USAGE };
+}
+
+// src/cli.ts
+var result = run(process.argv.slice(2), {
+  quiet: Boolean(process.env.AIRC_QUIET)
+});
+process.stdout.write(result.stdout);
+process.exit(result.code);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ardenthq/airc",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Shared Claude conventions for Ark/ArdentHQ repos — writes guideline files into a consumer repo's .claude/ardenthq/ and wires up the CLAUDE.md imports.",
   "license": "MIT",
   "type": "module",
@@ -14,24 +14,9 @@
   "engines": {
     "node": ">=18"
   },
-  "packageManager": "pnpm@10.0.0",
-  "scripts": {
-    "build": "tsup",
-    "format": "prettier --write \"**/*.{md,yaml,yml,json}\"",
-    "format:check": "prettier --check \"**/*.{md,yaml,yml,json}\"",
-    "lint": "eslint .",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
-  },
   "dependencies": {
     "yaml": "^2.6.1"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ]
-  },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
     "@types/node": "^22.10.2",
@@ -42,5 +27,14 @@
     "typescript": "^5.7.2",
     "typescript-eslint": "^8.18.1",
     "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsup",
+    "format": "prettier --write \"**/*.{md,yaml,yml,json}\"",
+    "format:check": "prettier --check \"**/*.{md,yaml,yml,json}\"",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   }
-}
+}