@aipper/aiws 0.0.1

package/src/commands/update.js

@@ -0,0 +1,98 @@
+import path from "node:path";
+import { loadTemplate } from "../spec.js";
+import { loadAiwsPackage } from "../aiws-package.js";
+import { resolveWorkspaceRoot } from "../workspace.js";
+import { readText, pathExists } from "../fs.js";
+import { UserError } from "../errors.js";
+import { normalizeNewlines } from "../hash.js";
+import { findManagedBlock } from "../managed-blocks.js";
+import { BackupSession } from "../backup.js";
+import { normalizeRel, joinRel } from "../path-utils.js";
+import { copyTemplateFileToWorkspace, applyManagedBlocksFromTemplate } from "../template.js";
+import { writeWorkspaceManifest } from "../manifest.js";
+
+/**
+ * @param {{ targetPath: string }} options
+ */
+export async function updateCommand(options) {
+  const workspaceRoot = await resolveWorkspaceRoot(options.targetPath, { create: false });
+  const aiws = await loadAiwsPackage();
+
+  const manifestPath = path.join(workspaceRoot, ".aiws", "manifest.json");
+  if (!(await pathExists(manifestPath))) {
+    throw new UserError("Missing .aiws/manifest.json. Run `aiws init` first.");
+  }
+  const stored = JSON.parse(await readText(manifestPath));
+  const templateId = String(stored.template_id || "workspace");
+  const tpl = await loadTemplate(templateId);
+
+  const update = tpl.manifest.update || {};
+  const replaceFiles = (update.replace_file || []).map(normalizeRel);
+  const managedBlocks = update.managed_blocks && typeof update.managed_blocks === "object" ? update.managed_blocks : {};
+
+  // Preflight: managed blocks must exist and be intact.
+  for (const [fileRelRaw, blockIdsRaw] of Object.entries(managedBlocks)) {
+    const fileRel = normalizeRel(fileRelRaw);
+    const abs = joinRel(workspaceRoot, fileRel);
+    if (!(await pathExists(abs))) {
+      throw new UserError("Managed block file missing; run `aiws init` or restore the file.", { details: `Missing: ${fileRel}` });
+    }
+    const text = normalizeNewlines(await readText(abs));
+    const ids = Array.isArray(blockIdsRaw) ? blockIdsRaw.map(String) : [];
+    for (const id of ids) {
+      if (!findManagedBlock(text, id)) {
+        throw new UserError("Managed block markers are missing or broken; refusing to update.", {
+          details: `File: ${fileRel}\nBlock: ${id}\nHint: re-run \`aiws init\` or repair markers manually.`,
+        });
+      }
+    }
+  }
+
+  const backup = new BackupSession({ workspaceRoot, operation: "update" });
+  // Backup every file we might touch (including missing, for rollback deletions).
+  await backup.recordFile(".aiws/manifest.json", { recordMissing: true });
+  for (const f of replaceFiles) await backup.recordFile(f, { recordMissing: true });
+  for (const f of Object.keys(managedBlocks)) await backup.recordFile(f, { recordMissing: true });
+  await backup.finalize({ extra: { template_id: tpl.templateId } });
+
+  // Replace files (except manifest, generated later).
+  for (const rel of replaceFiles) {
+    if (!rel || rel === ".aiws/manifest.json") continue;
+    await copyTemplateFileToWorkspace({
+      templateDir: tpl.templateDir,
+      workspaceRoot,
+      relPosix: rel,
+      chmod: rel.startsWith(".githooks/") ? 0o755 : undefined,
+    });
+  }
+
+  // Update managed blocks only (do not insert missing blocks).
+  for (const [fileRelRaw, blockIdsRaw] of Object.entries(managedBlocks)) {
+    const fileRel = normalizeRel(fileRelRaw);
+    const ids = Array.isArray(blockIdsRaw) ? blockIdsRaw.map(String) : [];
+    await applyManagedBlocksFromTemplate({
+      templateDir: tpl.templateDir,
+      workspaceRoot,
+      fileRel,
+      blockIds: ids,
+      insertIfMissing: false,
+    });
+  }
+
+  const now = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+  const installedAt = String(stored.installed_at || now);
+  const tools = Array.isArray(stored.tools) ? stored.tools.map(String) : ["claude", "opencode", "codex", "iflow"];
+
+  await writeWorkspaceManifest({
+    workspaceRoot,
+    templateId: tpl.templateId,
+    specVersion: tpl.specVersion,
+    aiwsVersion: aiws.version,
+    installedAt,
+    updatedAt: now,
+    tools,
+    templateManifest: tpl.manifest,
+  });
+
+  console.log(`✓ aiws update: ${workspaceRoot}`);
+}

package/src/commands/validate.js

@@ -0,0 +1,155 @@
+import path from "node:path";
+import { loadTemplate } from "../spec.js";
+import { resolveWorkspaceRoot } from "../workspace.js";
+import { ensureDir, pathExists, readText, writeText } from "../fs.js";
+import { UserError } from "../errors.js";
+import { validateDrift } from "../manifest.js";
+import { runCommand } from "../exec.js";
+import { expandManifestEntries } from "../template.js";
+import { loadAiwsPackage } from "../aiws-package.js";
+
+/**
+ * @param {string | undefined} v
+ */
+function envFlag(v) {
+  const s = String(v || "")
+    .trim()
+    .toLowerCase();
+  return s === "1" || s === "true" || s === "yes" || s === "y" || s === "on";
+}
+
+/**
+ * @returns {string} e.g. 20260204-140026Z
+ */
+function nowStampUtc() {
+  const d = new Date();
+  const y = String(d.getUTCFullYear());
+  const m = String(d.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(d.getUTCDate()).padStart(2, "0");
+  const hh = String(d.getUTCHours()).padStart(2, "0");
+  const mm = String(d.getUTCMinutes()).padStart(2, "0");
+  const ss = String(d.getUTCSeconds()).padStart(2, "0");
+  const ms = String(d.getUTCMilliseconds()).padStart(3, "0");
+  return `${y}${m}${day}-${hh}${mm}${ss}${ms}Z`;
+}
+
+/**
+ * @returns {string} e.g. 2026-01-28T14:00:26Z
+ */
+function nowIsoUtc() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+/**
+ * @param {any} error
+ * @returns {{ name: string, message: string, details?: string } | null}
+ */
+function serializeError(error) {
+  if (!error) return null;
+  if (error instanceof UserError) {
+    return { name: error.name, message: error.message, details: error.details };
+  }
+  if (error instanceof Error) {
+    return { name: error.name, message: error.message };
+  }
+  return { name: "Error", message: String(error) };
+}
+
+/**
+ * @param {{ targetPath: string, stamp?: boolean }} options
+ */
+export async function validateCommand(options) {
+  const stampEnabled = options.stamp === true || envFlag(process.env.AIWS_VALIDATE_STAMP);
+  const startedAt = nowIsoUtc();
+  const startedTs = Math.floor(Date.now() / 1000);
+  let workspaceRoot = "";
+  let templateId = "";
+  let specVersion = "";
+  let aiwsVersion = "";
+  let status = /** @type {"ok" | "error"} */ ("ok");
+  let exitCode = 0;
+  let err = null;
+  let stampPath = "";
+
+  try {
+    workspaceRoot = await resolveWorkspaceRoot(options.targetPath, { create: false });
+    const aiws = await loadAiwsPackage();
+    aiwsVersion = aiws.version;
+
+    const manifestPath = path.join(workspaceRoot, ".aiws", "manifest.json");
+    if (!(await pathExists(manifestPath))) {
+      throw new UserError("Missing .aiws/manifest.json. Run `aiws init` first.");
+    }
+    const stored = JSON.parse(await readText(manifestPath));
+    templateId = String(stored.template_id || "workspace");
+    const tpl = await loadTemplate(templateId);
+    specVersion = tpl.specVersion;
+
+    // Required files/dirs.
+    const required = await expandManifestEntries(tpl.templateDir, tpl.manifest.required || []);
+    /** @type {string[]} */
+    const missing = [];
+    for (const rel of required) {
+      const abs = path.join(workspaceRoot, ...String(rel).split("/"));
+      if (!(await pathExists(abs))) missing.push(rel);
+    }
+    if (missing.length > 0) {
+      throw new UserError("Missing required files.", { details: missing.join("\n") });
+    }
+
+    // Drift detection.
+    await validateDrift({ workspaceRoot, storedManifest: stored, templateManifest: tpl.manifest });
+
+    // python3 gate.
+    const py = await runCommand("python3", ["--version"], { cwd: workspaceRoot });
+    if (py.code !== 0) {
+      throw new UserError("python3 is required for validate.", { details: py.stderr || py.stdout });
+    }
+
+    // Required gate scripts.
+    const wsCheck = await runCommand("python3", ["tools/ws_change_check.py", "--strict"], { cwd: workspaceRoot });
+    if (wsCheck.code !== 0) {
+      throw new UserError("change gate failed.", { details: wsCheck.stderr || wsCheck.stdout });
+    }
+    const reqCheck = await runCommand("python3", ["tools/requirements_contract.py", "validate"], { cwd: workspaceRoot });
+    if (reqCheck.code !== 0) {
+      throw new UserError("requirements contract gate failed.", { details: reqCheck.stderr || reqCheck.stdout });
+    }
+
+    console.log(`✓ aiws validate: ${workspaceRoot}`);
+  } catch (error) {
+    status = "error";
+    err = serializeError(error);
+    if (error instanceof UserError) {
+      exitCode = error.exitCode;
+    } else {
+      exitCode = 1;
+    }
+    throw error;
+  } finally {
+    if (stampEnabled && workspaceRoot) {
+      try {
+        const stampDir = path.join(workspaceRoot, ".agentdocs", "tmp", "aiws-validate");
+        await ensureDir(stampDir);
+        stampPath = path.join(stampDir, `${nowStampUtc()}.json`);
+        const stamp = {
+          timestamp: startedTs,
+          ws_root: workspaceRoot,
+          template_id: templateId || null,
+          aiws_version: aiwsVersion || null,
+          spec_version: specVersion || null,
+          started_at: startedAt,
+          finished_at: nowIsoUtc(),
+          status,
+          exit_code: status === "ok" ? 0 : exitCode || 1,
+          error: err,
+          note: "aiws validate stamp; does not include full stdout/stderr; do not put secrets in validation output.",
+        };
+        await writeText(stampPath, JSON.stringify(stamp, null, 2) + "\n");
+        console.log(`stamp: ${path.relative(workspaceRoot, stampPath)}`);
+      } catch (e) {
+        console.error(`warn: failed to write validate stamp: ${e instanceof Error ? e.message : String(e)}`);
+      }
+    }
+  }
+}

package/src/errors.js

@@ -0,0 +1,15 @@
+export class UserError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ exitCode?: number, details?: string }=} options
+   */
+  constructor(message, options) {
+    super(message);
+    this.name = "UserError";
+    /** @type {number} */
+    this.exitCode = options?.exitCode ?? 2;
+    /** @type {string | undefined} */
+    this.details = options?.details;
+  }
+}
+

package/src/exec.js

@@ -0,0 +1,34 @@
+import { spawn } from "node:child_process";
+
+/**
+ * @param {string} command
+ * @param {string[]} args
+ * @param {{ cwd?: string }=} options
+ * @returns {Promise<{ code: number, stdout: string, stderr: string }>}
+ */
+export function runCommand(command, args, options) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options?.cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    /** @type {Buffer[]} */
+    const out = [];
+    /** @type {Buffer[]} */
+    const err = [];
+
+    child.stdout.on("data", (b) => out.push(Buffer.from(b)));
+    child.stderr.on("data", (b) => err.push(Buffer.from(b)));
+
+    child.on("error", (e) => reject(e));
+    child.on("close", (code) => {
+      resolve({
+        code: typeof code === "number" ? code : 1,
+        stdout: Buffer.concat(out).toString("utf8"),
+        stderr: Buffer.concat(err).toString("utf8"),
+      });
+    });
+  });
+}
+

package/src/fs.js

@@ -0,0 +1,91 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * @param {string} p
+ */
+export async function pathExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} p
+ */
+export async function ensureDir(p) {
+  await fs.mkdir(p, { recursive: true });
+}
+
+/**
+ * @param {string} p
+ */
+export async function readText(p) {
+  return await fs.readFile(p, "utf8");
+}
+
+/**
+ * @param {string} p
+ * @param {string} content
+ */
+export async function writeText(p, content) {
+  await ensureDir(path.dirname(p));
+  await fs.writeFile(p, content, "utf8");
+}
+
+/**
+ * @param {string} src
+ * @param {string} dest
+ * @param {{ chmod?: number }=} options
+ */
+export async function copyFile(src, dest, options) {
+  await ensureDir(path.dirname(dest));
+  await fs.copyFile(src, dest);
+  if (typeof options?.chmod === "number") {
+    await fs.chmod(dest, options.chmod);
+    return;
+  }
+  try {
+    const st = await fs.stat(src);
+    await fs.chmod(dest, st.mode & 0o777);
+  } catch {
+    // ignore chmod errors (e.g. on certain filesystems)
+  }
+}
+
+/**
+ * Very small glob support for patterns ending with `/**`.
+ *
+ * @param {string} rootDir
+ * @param {string} prefixDir
+ * @returns {Promise<string[]>} paths relative to rootDir
+ */
+export async function listFilesRecursive(rootDir, prefixDir) {
+  /** @type {string[]} */
+  const out = [];
+  const start = path.join(rootDir, prefixDir);
+  if (!(await pathExists(start))) return out;
+
+  /** @type {Array<{ abs: string, rel: string }>} */
+  const stack = [{ abs: start, rel: prefixDir }];
+  while (stack.length > 0) {
+    const cur = stack.pop();
+    if (!cur) break;
+    const entries = await fs.readdir(cur.abs, { withFileTypes: true });
+    for (const ent of entries) {
+      const abs = path.join(cur.abs, ent.name);
+      const rel = path.posix.join(cur.rel.replaceAll(path.sep, "/"), ent.name);
+      if (ent.isDirectory()) {
+        stack.push({ abs, rel });
+      } else if (ent.isFile()) {
+        out.push(rel);
+      }
+    }
+  }
+  out.sort();
+  return out;
+}
+

package/src/hash.js

@@ -0,0 +1,25 @@
+import crypto from "node:crypto";
+import { readText } from "./fs.js";
+
+/**
+ * @param {string} s
+ */
+export function normalizeNewlines(s) {
+  return s.replaceAll("\r\n", "\n");
+}
+
+/**
+ * @param {string} text
+ */
+export function sha256Text(text) {
+  return crypto.createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+/**
+ * @param {string} filePath
+ */
+export async function sha256FileText(filePath) {
+  const content = normalizeNewlines(await readText(filePath));
+  return sha256Text(content);
+}
+

package/src/managed-blocks.js

@@ -0,0 +1,131 @@
+import { normalizeNewlines, sha256Text } from "./hash.js";
+import { UserError } from "./errors.js";
+
+/**
+ * @param {string} s
+ * @returns {string}
+ */
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * @param {string} text
+ * @param {string} blockId
+ * @returns {{ beginLineIndex: number, endLineIndex: number, innerText: string, beginLine: string, endLine: string } | null}
+ */
+export function findManagedBlock(text, blockId) {
+  const t = normalizeNewlines(text);
+  const lines = t.split("\n");
+  const beginRe = new RegExp(`AIWS_MANAGED_BEGIN:${escapeRegExp(blockId)}(?:\\s|$|-->)`);
+  const endRe = new RegExp(`AIWS_MANAGED_END:${escapeRegExp(blockId)}(?:\\s|$|-->)`);
+
+  let beginLineIndex = -1;
+  let endLineIndex = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (beginLineIndex === -1 && beginRe.test(lines[i] ?? "")) {
+      beginLineIndex = i;
+      continue;
+    }
+    if (beginLineIndex !== -1 && endRe.test(lines[i] ?? "")) {
+      endLineIndex = i;
+      break;
+    }
+  }
+
+  if (beginLineIndex === -1 || endLineIndex === -1 || endLineIndex <= beginLineIndex) return null;
+
+  const innerLines = lines.slice(beginLineIndex + 1, endLineIndex);
+  let innerText = innerLines.join("\n");
+  if (innerLines.length > 0) innerText += "\n";
+
+  return {
+    beginLineIndex,
+    endLineIndex,
+    innerText,
+    beginLine: lines[beginLineIndex] ?? "",
+    endLine: lines[endLineIndex] ?? "",
+  };
+}
+
+/**
+ * Extract the canonical block chunk (begin+inner+end) from a template file.
+ *
+ * @param {string} templateText
+ * @param {string} blockId
+ * @returns {{ blockChunk: string, innerText: string }}
+ */
+export function extractTemplateBlock(templateText, blockId) {
+  const t = normalizeNewlines(templateText);
+  const block = findManagedBlock(t, blockId);
+  if (!block) {
+    throw new UserError(`Template is missing managed block: ${blockId}`, { exitCode: 1 });
+  }
+  const blockChunk = `${block.beginLine}\n${block.innerText}${block.endLine}\n`;
+  return { blockChunk, innerText: block.innerText };
+}
+
+/**
+ * @param {string} targetText
+ * @param {string} blockId
+ * @param {string} newInnerText normalized; may end with "\n"
+ * @param {{ insertIfMissing: boolean, templateBlockChunk?: string } } options
+ * @returns {{ nextText: string, changed: boolean, inserted: boolean }}
+ */
+export function upsertManagedBlock(targetText, blockId, newInnerText, options) {
+  const original = normalizeNewlines(targetText);
+  const block = findManagedBlock(original, blockId);
+  if (!block) {
+    if (!options.insertIfMissing) {
+      throw new UserError(`Missing managed block: ${blockId}`);
+    }
+    if (!options.templateBlockChunk) {
+      throw new UserError(`Cannot insert managed block without template chunk: ${blockId}`, { exitCode: 1 });
+    }
+    const nextText = insertBlockAtTop(original, options.templateBlockChunk);
+    return { nextText, changed: true, inserted: true };
+  }
+
+  const lines = original.split("\n");
+  const begin = lines.slice(0, block.beginLineIndex + 1);
+  const end = lines.slice(block.endLineIndex);
+
+  const innerLines = newInnerText.endsWith("\n") ? newInnerText.slice(0, -1).split("\n") : newInnerText.split("\n");
+  const rebuilt = [...begin, ...innerLines, ...end].join("\n");
+
+  return { nextText: rebuilt, changed: rebuilt !== original, inserted: false };
+}
+
+/**
+ * Insert block chunk near the top with minimal disruption:
+ * - If the file starts with a Markdown heading (`# ...`), insert after the first line.
+ * - Otherwise, insert at the very top.
+ *
+ * @param {string} text normalized
+ * @param {string} blockChunk normalized; should end with "\n"
+ */
+function insertBlockAtTop(text, blockChunk) {
+  const t = normalizeNewlines(text);
+  const chunk = normalizeNewlines(blockChunk).endsWith("\n") ? normalizeNewlines(blockChunk) : `${normalizeNewlines(blockChunk)}\n`;
+
+  const lines = t.split("\n");
+  if (lines.length > 0 && (lines[0] ?? "").startsWith("# ")) {
+    const after = lines.slice(1).join("\n");
+    const head = `${lines[0]}\n`;
+    return `${head}\n${chunk}\n${after}`.replace(/\n{3,}/g, "\n\n");
+  }
+  return `${chunk}\n${t}`.replace(/\n{3,}/g, "\n\n");
+}
+
+/**
+ * @param {string} text
+ * @param {string} blockId
+ */
+export function hashManagedBlockInner(text, blockId) {
+  const block = findManagedBlock(text, blockId);
+  if (!block) {
+    throw new UserError(`Missing managed block: ${blockId}`);
+  }
+  return sha256Text(block.innerText);
+}