@aipper/aiws 0.0.1

package/src/cli.js

@@ -0,0 +1,470 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { UserError } from "./errors.js";
+import { initCommand } from "./commands/init.js";
+import { updateCommand } from "./commands/update.js";
+import { validateCommand } from "./commands/validate.js";
+import { rollbackCommand } from "./commands/rollback.js";
+import { codexInstallPromptsCommand } from "./commands/codex-install-prompts.js";
+import { codexStatusPromptsCommand } from "./commands/codex-status-prompts.js";
+import { codexUninstallPromptsCommand } from "./commands/codex-uninstall-prompts.js";
+import { codexInstallSkillsCommand } from "./commands/codex-install-skills.js";
+import { codexStatusSkillsCommand } from "./commands/codex-status-skills.js";
+import { codexUninstallSkillsCommand } from "./commands/codex-uninstall-skills.js";
+import { hooksInstallCommand } from "./commands/hooks-install.js";
+import { hooksStatusCommand } from "./commands/hooks-status.js";
+import {
+  changeArchiveCommand,
+  changeListCommand,
+  changeNewCommand,
+  changeNextCommand,
+  changeStartCommand,
+  changeStatusCommand,
+  changeSyncCommand,
+  changeTemplatesInitCommand,
+  changeTemplatesWhichCommand,
+  changeValidateCommand,
+} from "./commands/change.js";
+
+/**
+ * @param {string[]} argv
+ * @returns {Promise<number>} exit code
+ */
+export async function cliMain(argv) {
+  const args = argv.slice();
+  if (args[0] === "codex" && (args.includes("-h") || args.includes("--help"))) {
+    printCodexHelp();
+    return 0;
+  }
+  if (args[0] === "hooks" && (args.includes("-h") || args.includes("--help"))) {
+    printHooksHelp();
+    return 0;
+  }
+  if (args[0] === "change" && (args.includes("-h") || args.includes("--help"))) {
+    printChangeHelp();
+    return 0;
+  }
+  if (args.length === 0 || args.includes("-h") || args.includes("--help") || args[0] === "help") {
+    printHelp();
+    return 0;
+  }
+  if (args[0] === "--version" || args[0] === "-v") {
+    console.log(getAiwsVersion());
+    return 0;
+  }
+
+  const cmd = args.shift();
+  if (!cmd) {
+    printHelp();
+    return 0;
+  }
+
+  switch (cmd) {
+    case "init": {
+      const { positionals, options } = parseArgs(args, {
+        template: { type: "string" },
+      });
+      const targetPath = positionals[0] ?? ".";
+      const templateId = options.template ?? "workspace";
+      await initCommand({ targetPath, templateId });
+      return 0;
+    }
+    case "update": {
+      const { positionals } = parseArgs(args, {});
+      const targetPath = positionals[0] ?? ".";
+      await updateCommand({ targetPath });
+      return 0;
+    }
+    case "validate": {
+      const { positionals, options } = parseArgs(args, {
+        stamp: { type: "boolean" },
+      });
+      const targetPath = positionals[0] ?? ".";
+      await validateCommand({ targetPath, stamp: options.stamp === true });
+      return 0;
+    }
+    case "rollback": {
+      const { positionals } = parseArgs(args, {});
+      if (positionals.length === 0) {
+        throw new UserError("rollback requires <timestamp|latest>", { details: "Usage: aiws rollback [path] <timestamp|latest>" });
+      }
+      let targetPath = ".";
+      let stamp = "";
+      if (positionals.length === 1) {
+        stamp = positionals[0] ?? "";
+      } else {
+        targetPath = positionals[0] ?? ".";
+        stamp = positionals[1] ?? "";
+      }
+      await rollbackCommand({ targetPath, stamp });
+      return 0;
+    }
+    case "codex": {
+      const sub = args.shift();
+      if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+        printCodexHelp();
+        return 0;
+      }
+      switch (sub) {
+        case "install-skills": {
+          const { options } = parseArgs(args, {
+            template: { type: "string" },
+            dir: { type: "string" },
+            force: { type: "boolean" },
+            "dry-run": { type: "boolean" },
+          });
+          await codexInstallSkillsCommand({
+            templateId: options.template ?? "workspace",
+            skillsDir: options.dir,
+            force: options.force === true,
+            dryRun: options["dry-run"] === true,
+          });
+          return 0;
+        }
+        case "status-skills": {
+          const { options } = parseArgs(args, {
+            template: { type: "string" },
+            dir: { type: "string" },
+          });
+          await codexStatusSkillsCommand({
+            templateId: options.template ?? "workspace",
+            skillsDir: options.dir,
+          });
+          return 0;
+        }
+        case "uninstall-skills": {
+          const { options } = parseArgs(args, {
+            template: { type: "string" },
+            dir: { type: "string" },
+          });
+          await codexUninstallSkillsCommand({
+            templateId: options.template ?? "workspace",
+            skillsDir: options.dir,
+          });
+          return 0;
+        }
+        case "install-prompts": {
+          const { options } = parseArgs(args, {
+            template: { type: "string" },
+            dir: { type: "string" },
+            force: { type: "boolean" },
+            "dry-run": { type: "boolean" },
+          });
+          await codexInstallPromptsCommand({
+            templateId: options.template ?? "workspace",
+            promptsDir: options.dir,
+            force: options.force === true,
+            dryRun: options["dry-run"] === true,
+          });
+          return 0;
+        }
+        case "status": {
+          const { options } = parseArgs(args, {
+            template: { type: "string" },
+            dir: { type: "string" },
+          });
+          await codexStatusPromptsCommand({
+            templateId: options.template ?? "workspace",
+            promptsDir: options.dir,
+          });
+          return 0;
+        }
+        case "uninstall-prompts": {
+          const { options } = parseArgs(args, {
+            template: { type: "string" },
+            dir: { type: "string" },
+          });
+          await codexUninstallPromptsCommand({
+            templateId: options.template ?? "workspace",
+            promptsDir: options.dir,
+          });
+          return 0;
+        }
+        default:
+          throw new UserError(`Unknown codex subcommand: ${sub}`, { details: "Use `aiws codex --help` to see available subcommands." });
+      }
+    }
+    case "hooks": {
+      const sub = args.shift();
+      if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+        printHooksHelp();
+        return 0;
+      }
+      switch (sub) {
+        case "install": {
+          const { positionals } = parseArgs(args, {});
+          const targetPath = positionals[0] ?? ".";
+          await hooksInstallCommand({ targetPath });
+          return 0;
+        }
+        case "status": {
+          const { positionals } = parseArgs(args, {});
+          const targetPath = positionals[0] ?? ".";
+          await hooksStatusCommand({ targetPath });
+          return 0;
+        }
+        default:
+          throw new UserError(`Unknown hooks subcommand: ${sub}`, { details: "Use `aiws hooks --help` to see available subcommands." });
+      }
+    }
+    case "change": {
+      const sub = args.shift();
+      if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+        printChangeHelp();
+        return 0;
+      }
+      switch (sub) {
+        case "list": {
+          await changeListCommand();
+          return 0;
+        }
+        case "start": {
+          const { positionals, options } = parseArgs(args, {
+            title: { type: "string" },
+            "no-design": { type: "boolean" },
+            hooks: { type: "boolean" },
+          });
+          const changeId = positionals[0] ?? "";
+          if (!changeId) throw new UserError("change start requires <change-id>", { details: "Usage: aiws change start <change-id> [--title <title>] [--no-design] [--hooks]" });
+          await changeStartCommand({
+            changeId,
+            title: options.title,
+            noDesign: options["no-design"] === true,
+            enableHooks: options.hooks === true,
+          });
+          return 0;
+        }
+        case "new": {
+          const { positionals, options } = parseArgs(args, {
+            title: { type: "string" },
+            "no-design": { type: "boolean" },
+          });
+          const changeId = positionals[0] ?? "";
+          if (!changeId) throw new UserError("change new requires <change-id>", { details: "Usage: aiws change new <change-id> [--title <title>] [--no-design]" });
+          await changeNewCommand({
+            changeId,
+            title: options.title,
+            noDesign: options["no-design"] === true,
+          });
+          return 0;
+        }
+        case "status": {
+          const { positionals } = parseArgs(args, {});
+          const changeId = positionals[0];
+          await changeStatusCommand({ changeId });
+          return 0;
+        }
+        case "next": {
+          const { positionals } = parseArgs(args, {});
+          const changeId = positionals[0];
+          await changeNextCommand({ changeId });
+          return 0;
+        }
+        case "validate": {
+          const { positionals, options } = parseArgs(args, {
+            strict: { type: "boolean" },
+            "allow-truth-drift": { type: "boolean" },
+          });
+          const changeId = positionals[0];
+          await changeValidateCommand({
+            changeId,
+            strict: options.strict === true,
+            allowTruthDrift: options["allow-truth-drift"] === true,
+          });
+          return 0;
+        }
+        case "sync": {
+          const { positionals } = parseArgs(args, {});
+          const changeId = positionals[0];
+          await changeSyncCommand({ changeId });
+          return 0;
+        }
+        case "archive": {
+          const { positionals, options } = parseArgs(args, {
+            date: { type: "string" },
+            force: { type: "boolean" },
+          });
+          const changeId = positionals[0];
+          await changeArchiveCommand({
+            changeId,
+            datePrefix: options.date,
+            force: options.force === true,
+          });
+          return 0;
+        }
+        case "templates": {
+          const templatesSub = args.shift();
+          if (!templatesSub) throw new UserError("change templates requires <which|init>", { details: "Usage: aiws change templates which|init" });
+          if (templatesSub === "which") {
+            const { positionals } = parseArgs(args, {});
+            if (positionals.length > 0) throw new UserError("change templates which takes no args");
+            await changeTemplatesWhichCommand();
+            return 0;
+          }
+          if (templatesSub === "init") {
+            const { positionals } = parseArgs(args, {});
+            if (positionals.length > 0) throw new UserError("change templates init takes no args");
+            await changeTemplatesInitCommand();
+            return 0;
+          }
+          throw new UserError(`Unknown change templates subcommand: ${templatesSub}`, { details: "Use `aiws change --help` to see available commands." });
+        }
+        default:
+          throw new UserError(`Unknown change subcommand: ${sub}`, { details: "Use `aiws change --help` to see available subcommands." });
+      }
+    }
+    default:
+      throw new UserError(`Unknown command: ${cmd}`, { details: "Use --help to see available commands." });
+  }
+}
+
+function printHelp() {
+  console.log(`aiws (WORK IN PROGRESS)
+
+Usage:
+  aiws init [path] [--template <id>]
+  aiws update [path]
+  aiws validate [path] [--stamp]
+  aiws rollback [path] <timestamp|latest>
+  aiws change <subcommand>
+  aiws codex <subcommand>
+  aiws hooks <subcommand>
+
+Options:
+  --template <id>   Template id (default: workspace)
+  --stamp           Write evidence stamp (validate)
+  -h, --help        Show help
+  -v, --version     Show version
+`);
+}
+
+function printCodexHelp() {
+  console.log(`aiws codex
+
+Usage:
+  aiws codex install-skills [--template <id>] [--dir <path>] [--force] [--dry-run]
+  aiws codex status-skills [--template <id>] [--dir <path>]
+  aiws codex uninstall-skills [--template <id>] [--dir <path>]
+  aiws codex install-prompts [--template <id>] [--dir <path>] [--force] [--dry-run]
+  aiws codex status [--template <id>] [--dir <path>]
+  aiws codex uninstall-prompts [--template <id>] [--dir <path>]
+
+Notes:
+  - Prefer repo skills: .agents/skills (no install needed)
+  - Prefer global skills over legacy prompts
+  - Default skills dir: ~/.codex/skills (or $CODEX_HOME/skills)
+  - install-prompts is legacy (prompts are deprecated)
+  - Default target dir: ~/.codex/prompts
+  - If CODEX_HOME is set: $CODEX_HOME/prompts
+`);
+}
+
+function printHooksHelp() {
+  console.log(`aiws hooks
+
+Usage:
+  aiws hooks install [path]
+  aiws hooks status [path]
+
+Notes:
+  - install will set: git config core.hooksPath .githooks
+  - hooks can be bypassed with: WS_CHANGE_HOOK_BYPASS=1
+`);
+}
+
+function printChangeHelp() {
+  console.log(`aiws change
+
+Usage:
+  aiws change list
+  aiws change start <change-id> [--title <title>] [--no-design] [--hooks]
+  aiws change new <change-id> [--title <title>] [--no-design]
+  aiws change status [change-id]
+  aiws change next [change-id]
+  aiws change validate [change-id] [--strict] [--allow-truth-drift]
+  aiws change sync [change-id]
+  aiws change archive [change-id] [--date YYYY-MM-DD] [--force]
+  aiws change templates which
+  aiws change templates init
+
+Notes:
+  - change-id must be kebab-case: ^[a-z0-9]+(-[a-z0-9]+)*$
+  - If your git branch matches change/<change-id> (or changes/ws/ws-change prefixes),
+    you can omit <change-id> for status/next/validate/sync/archive.
+  - archive runs strict validation and (by default) requires all tasks checked.
+  - archive --force also bypasses truth drift gating (not recommended).
+`);
+}
+
+/**
+ * Minimal argv parser:
+ * - supports: --k=v, --k v
+ * - collects unknown flags as error
+ *
+ * @param {string[]} argv
+ * @param {Record<string, { type: "string" | "boolean" }>} schema
+ * @returns {{ positionals: string[], options: Record<string, any> }}
+ */
+function parseArgs(argv, schema) {
+  /** @type {string[]} */
+  const positionals = [];
+  /** @type {Record<string, any>} */
+  const options = {};
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i] ?? "";
+    if (!a.startsWith("-")) {
+      positionals.push(a);
+      continue;
+    }
+    if (a === "--") {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (!a.startsWith("--")) {
+      throw new UserError(`Unknown option: ${a}`);
+    }
+    const eq = a.indexOf("=");
+    const key = (eq === -1 ? a.slice(2) : a.slice(2, eq)).trim();
+    if (!schema[key]) {
+      throw new UserError(`Unknown option: --${key}`);
+    }
+    const type = schema[key]?.type;
+    if (type === "boolean") {
+      if (eq !== -1) {
+        const raw = a.slice(eq + 1).trim().toLowerCase();
+        options[key] = raw === "1" || raw === "true" || raw === "yes" || raw === "y" || raw === "on";
+      } else {
+        options[key] = true;
+      }
+      continue;
+    }
+
+    let value = "";
+    if (eq !== -1) {
+      value = a.slice(eq + 1);
+    } else {
+      const next = argv[i + 1];
+      if (!next || next.startsWith("-")) {
+        throw new UserError(`Missing value for --${key}`);
+      }
+      value = next;
+      i++;
+    }
+    options[key] = value;
+  }
+
+  return { positionals, options };
+}
+
+function getAiwsVersion() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const pkgPath = path.resolve(here, "../package.json");
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return String(pkg.version || "").trim() || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}

package/src/codex-prompts.js

@@ -0,0 +1,74 @@
+import os from "node:os";
+import path from "node:path";
+import { listFilesRecursive, readText } from "./fs.js";
+import { normalizeNewlines } from "./hash.js";
+import { extractTemplateBlock } from "./managed-blocks.js";
+import { UserError } from "./errors.js";
+
+/**
+ * Resolve Codex global prompts directory:
+ * - If `--dir` provided, use it directly.
+ * - Else if `CODEX_HOME` is set, use `$CODEX_HOME/prompts`.
+ * - Else use `~/.codex/prompts`.
+ *
+ * @param {string | undefined} dirOption
+ */
+export function resolveCodexPromptsDir(dirOption) {
+  if (dirOption) return path.resolve(dirOption);
+  const envHome = String(process.env.CODEX_HOME || "").trim();
+  if (envHome) return path.join(path.resolve(envHome), "prompts");
+  return path.join(os.homedir(), ".codex", "prompts");
+}
+
+function timestamp() {
+  const d = new Date();
+  // 2026-01-28T12:34:56Z -> 20260128-123456Z
+  return d.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z").replace("T", "-");
+}
+
+export function codexBackupStamp() {
+  return timestamp();
+}
+
+/**
+ * @param {string} promptsDir
+ * @param {string} filename
+ * @param {string=} stamp
+ */
+export function codexBackupPathFor(promptsDir, filename, stamp) {
+  return path.join(promptsDir, ".aiws", "backups", "codex-prompts", stamp || timestamp(), filename);
+}
+
+/**
+ * List Codex prompt files in a template and extract their managed block inner text.
+ *
+ * @param {{ templateId: string, templateDir: string }} tpl
+ * @returns {Promise<Array<{ rel: string, filename: string, name: string, blockId: string, srcAbs: string, templateText: string, innerText: string }>>}
+ */
+export async function listTemplateCodexPrompts(tpl) {
+  const relFiles = await listFilesRecursive(tpl.templateDir, ".codex/prompts");
+  const promptFiles = relFiles
+    .filter((rel) => rel.startsWith(".codex/prompts/"))
+    .filter((rel) => rel.split("/").length === 3)
+    .filter((rel) => rel.toLowerCase().endsWith(".md"));
+
+  if (promptFiles.length === 0) {
+    throw new UserError(`Template has no Codex prompt files: ${tpl.templateId}`, {
+      details: `Missing under: ${path.join(tpl.templateDir, ".codex", "prompts")}`,
+      exitCode: 1,
+    });
+  }
+
+  /** @type {Array<{ rel: string, filename: string, name: string, blockId: string, srcAbs: string, templateText: string, innerText: string }>} */
+  const out = [];
+  for (const rel of promptFiles) {
+    const filename = path.posix.basename(rel);
+    const name = filename.replace(/\.md$/i, "");
+    const blockId = `codex:${name}`;
+    const srcAbs = path.join(tpl.templateDir, ...rel.split("/"));
+    const templateText = normalizeNewlines(await readText(srcAbs));
+    const { innerText } = extractTemplateBlock(templateText, blockId);
+    out.push({ rel, filename, name, blockId, srcAbs, templateText, innerText });
+  }
+  return out;
+}

package/src/codex-skills.js

@@ -0,0 +1,111 @@
+import os from "node:os";
+import path from "node:path";
+import { listFilesRecursive, readText } from "./fs.js";
+import { normalizeNewlines } from "./hash.js";
+import { UserError } from "./errors.js";
+
+/**
+ * Resolve Codex global skills directory:
+ * - If `--dir` provided, use it directly.
+ * - Else if `CODEX_HOME` is set, use `$CODEX_HOME/skills`.
+ * - Else use `~/.codex/skills`.
+ *
+ * @param {string | undefined} dirOption
+ */
+export function resolveCodexSkillsDir(dirOption) {
+  if (dirOption) return path.resolve(dirOption);
+  const envHome = String(process.env.CODEX_HOME || "").trim();
+  if (envHome) return path.join(path.resolve(envHome), "skills");
+  return path.join(os.homedir(), ".codex", "skills");
+}
+
+function timestamp() {
+  const d = new Date();
+  // 2026-01-28T12:34:56Z -> 20260128-123456Z
+  return d.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z").replace("T", "-");
+}
+
+export function codexSkillsBackupStamp() {
+  return timestamp();
+}
+
+/**
+ * @param {string} skillsDir
+ * @param {string} skillName
+ * @param {string=} stamp
+ */
+export function codexSkillsBackupPathFor(skillsDir, skillName, stamp) {
+  return path.join(skillsDir, ".aiws", "backups", "codex-skills", stamp || timestamp(), skillName, "SKILL.md");
+}
+
+/**
+ * @param {string} text normalized
+ * @returns {{ frontMatter: string, body: string }}
+ */
+function splitYamlFrontMatter(text) {
+  const t = normalizeNewlines(text);
+  const lines = t.split("\n");
+  if ((lines[0] ?? "") !== "---") {
+    throw new UserError("Invalid SKILL.md: missing YAML front matter at top", { exitCode: 1 });
+  }
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if ((lines[i] ?? "") === "---") {
+      end = i;
+      break;
+    }
+  }
+  if (end === -1) {
+    throw new UserError("Invalid SKILL.md: YAML front matter not closed", { exitCode: 1 });
+  }
+
+  const frontMatter = `${lines.slice(0, end + 1).join("\n")}\n`;
+  const body = lines.slice(end + 1).join("\n");
+  return { frontMatter, body };
+}
+
+/**
+ * List Codex repo skills in a template and prepare a managed-file wrapper for global installation.
+ *
+ * The wrapper adds an AIWS managed block after YAML front matter so updates can preserve user-added
+ * text outside the managed block.
+ *
+ * @param {{ templateId: string, templateDir: string }} tpl
+ * @returns {Promise<Array<{ rel: string, skillName: string, blockId: string, srcAbs: string, templateText: string, managedText: string, innerText: string }>>}
+ */
+export async function listTemplateCodexSkills(tpl) {
+  const relFiles = await listFilesRecursive(tpl.templateDir, ".agents/skills");
+  const skillFiles = relFiles
+    .filter((rel) => rel.startsWith(".agents/skills/"))
+    .filter((rel) => rel.split("/").length === 4)
+    .filter((rel) => rel.toLowerCase().endsWith("/skill.md"));
+
+  if (skillFiles.length === 0) {
+    throw new UserError(`Template has no Codex skills: ${tpl.templateId}`, {
+      details: `Missing under: ${path.join(tpl.templateDir, ".agents", "skills")}`,
+      exitCode: 1,
+    });
+  }
+
+  /** @type {Array<{ rel: string, skillName: string, blockId: string, srcAbs: string, templateText: string, managedText: string, innerText: string }>} */
+  const out = [];
+  for (const rel of skillFiles) {
+    const parts = rel.split("/");
+    const skillName = parts[2] ?? "";
+    if (!skillName) continue;
+    const blockId = `codex-skill:${skillName}`;
+    const srcAbs = path.join(tpl.templateDir, ...rel.split("/"));
+    const templateText = normalizeNewlines(await readText(srcAbs));
+    const { frontMatter, body } = splitYamlFrontMatter(templateText);
+
+    const innerTextRaw = normalizeNewlines(body);
+    const innerText = innerTextRaw.endsWith("\n") ? innerTextRaw : `${innerTextRaw}\n`;
+
+    const begin = `<!-- AIWS_MANAGED_BEGIN:${blockId} -->`;
+    const end = `<!-- AIWS_MANAGED_END:${blockId} -->`;
+    const managedText = `${frontMatter}\n${begin}\n${innerText}${end}\n`;
+
+    out.push({ rel, skillName, blockId, srcAbs, templateText, managedText, innerText });
+  }
+  return out;
+}