@aipper/aiws 0.0.1

package/src/manifest.js

@@ -0,0 +1,153 @@
+import path from "node:path";
+import { normalizeNewlines, sha256FileText, sha256Text } from "./hash.js";
+import { joinRel, normalizeRel } from "./path-utils.js";
+import { pathExists, readText, writeText } from "./fs.js";
+import { findManagedBlock } from "./managed-blocks.js";
+import { UserError } from "./errors.js";
+
+/**
+ * @param {any} manifest
+ */
+export function isPlaceholderManifest(manifest) {
+  if (!manifest || typeof manifest !== "object") return true;
+  if (manifest.installed_at === "1970-01-01T00:00:00Z" || manifest.updated_at === "1970-01-01T00:00:00Z") return true;
+
+  const managed = Array.isArray(manifest.managed) ? manifest.managed : [];
+  for (const m of managed) {
+    if (!m || typeof m !== "object") continue;
+    if (typeof m.sha256 === "string" && m.sha256.includes("<sha256>")) return true;
+    if (m.blocks && typeof m.blocks === "object") {
+      for (const v of Object.values(m.blocks)) {
+        if (typeof v === "string" && v.includes("<sha256>")) return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * @param {{ workspaceRoot: string, templateId: string, specVersion: string, aiwsVersion: string, installedAt: string, updatedAt: string, tools: string[], templateManifest: any }} options
+ */
+export async function writeWorkspaceManifest(options) {
+  const managed = await computeManagedState({
+    workspaceRoot: options.workspaceRoot,
+    templateManifest: options.templateManifest,
+  });
+
+  const obj = {
+    manifest_version: 1,
+    template_id: options.templateId,
+    spec_version: options.specVersion,
+    aiws_version: options.aiwsVersion,
+    installed_at: options.installedAt,
+    updated_at: options.updatedAt,
+    tools: options.tools,
+    managed,
+  };
+
+  const outPath = path.join(options.workspaceRoot, ".aiws", "manifest.json");
+  await writeText(outPath, JSON.stringify(obj, null, 2) + "\n");
+  return obj;
+}
+
+/**
+ * Compute managed hashes for the current workspace.
+ *
+ * Note: `.aiws/manifest.json` is intentionally excluded from `managed` to avoid self-hashing.
+ *
+ * @param {{ workspaceRoot: string, templateManifest: any }} options
+ */
+export async function computeManagedState(options) {
+  const update = options.templateManifest?.update || {};
+  const replaceFiles = Array.isArray(update.replace_file) ? update.replace_file : [];
+  const managedBlocks = update.managed_blocks && typeof update.managed_blocks === "object" ? update.managed_blocks : {};
+
+  /** @type {any[]} */
+  const out = [];
+
+  for (const relRaw of replaceFiles) {
+    const rel = normalizeRel(relRaw);
+    if (!rel || rel === ".aiws/manifest.json") continue;
+    const abs = joinRel(options.workspaceRoot, rel);
+    if (!(await pathExists(abs))) throw new UserError(`Missing required managed file: ${rel}`);
+    out.push({ path: rel, mode: "replace_file", sha256: await sha256FileText(abs) });
+  }
+
+  for (const [fileRelRaw, blockIdsRaw] of Object.entries(managedBlocks)) {
+    const fileRel = normalizeRel(fileRelRaw);
+    if (!fileRel) continue;
+    const abs = joinRel(options.workspaceRoot, fileRel);
+    if (!(await pathExists(abs))) throw new UserError(`Missing required managed file: ${fileRel}`);
+    const text = normalizeNewlines(await readText(abs));
+    /** @type {Record<string, string>} */
+    const blocks = {};
+    const ids = Array.isArray(blockIdsRaw) ? blockIdsRaw : [];
+    for (const idRaw of ids) {
+      const id = String(idRaw);
+      const found = findManagedBlock(text, id);
+      if (!found) throw new UserError(`Missing managed block: ${id}`, { details: `File: ${fileRel}` });
+      blocks[id] = sha256Text(found.innerText);
+    }
+    out.push({ path: fileRel, mode: "managed_blocks", blocks });
+  }
+
+  out.sort((a, b) => String(a.path).localeCompare(String(b.path)));
+  return out;
+}
+
+/**
+ * Validate current workspace against the stored `.aiws/manifest.json` and template contract.
+ *
+ * @param {{ workspaceRoot: string, storedManifest: any, templateManifest: any }} options
+ */
+export async function validateDrift(options) {
+  const stored = options.storedManifest;
+  if (isPlaceholderManifest(stored)) {
+    throw new UserError("Workspace manifest is placeholder/uninitialized.", {
+      details: "Run `aiws init` to generate a real .aiws/manifest.json.",
+    });
+  }
+
+  const expected = await computeManagedState({ workspaceRoot: options.workspaceRoot, templateManifest: options.templateManifest });
+  const currentByPath = new Map(expected.map((e) => [e.path, e]));
+
+  const managed = Array.isArray(stored.managed) ? stored.managed : [];
+  const storedByPath = new Map(managed.map((e) => [String(e.path || ""), e]));
+
+  /** @type {string[]} */
+  const problems = [];
+
+  for (const [p, cur] of currentByPath.entries()) {
+    const s = storedByPath.get(p);
+    if (!s) {
+      problems.push(`missing manifest entry: ${p}`);
+      continue;
+    }
+    if (cur.mode !== s.mode) {
+      problems.push(`mode mismatch: ${p} (expected ${cur.mode}, got ${s.mode})`);
+      continue;
+    }
+    if (cur.mode === "replace_file") {
+      if (cur.sha256 !== s.sha256) {
+        problems.push(`sha256 mismatch: ${p}`);
+      }
+      continue;
+    }
+    if (cur.mode === "managed_blocks") {
+      const curBlocks = cur.blocks || {};
+      const sBlocks = s.blocks || {};
+      for (const [bid, curSha] of Object.entries(curBlocks)) {
+        if (!sBlocks[bid]) {
+          problems.push(`missing block in manifest: ${p} (${bid})`);
+        } else if (sBlocks[bid] !== curSha) {
+          problems.push(`block sha256 mismatch: ${p} (${bid})`);
+        }
+      }
+    }
+  }
+
+  if (problems.length > 0) {
+    throw new UserError("Workspace drift detected.", { details: problems.join("\n") });
+  }
+}
+

package/src/path-utils.js

@@ -0,0 +1,20 @@
+import path from "node:path";
+
+/**
+ * Join a POSIX-style relative path (with `/`) onto an absolute root.
+ *
+ * @param {string} rootDir
+ * @param {string} relPosix
+ */
+export function joinRel(rootDir, relPosix) {
+  return path.join(rootDir, ...String(relPosix).split("/"));
+}
+
+/**
+ * Normalize a relative path from manifest (always forward slashes).
+ *
+ * @param {string} rel
+ */
+export function normalizeRel(rel) {
+  return String(rel).replaceAll("\\", "/").replaceAll(/\/+/g, "/").replace(/^\/+/, "");
+}

package/src/spec.js

@@ -0,0 +1,64 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { pathExists, readText } from "./fs.js";
+import { UserError } from "./errors.js";
+
+/**
+ * @returns {Promise<{ rootDir: string, version: string }>}
+ */
+export async function loadSpecPackage() {
+  const require = createRequire(import.meta.url);
+
+  /** @type {string | null} */
+  let pkgJsonPath = null;
+  try {
+    pkgJsonPath = require.resolve("@aipper/aiws-spec/package.json");
+  } catch {
+    pkgJsonPath = null;
+  }
+
+  /** @type {string} */
+  let rootDir;
+  if (pkgJsonPath) {
+    rootDir = path.dirname(pkgJsonPath);
+  } else {
+    const here = fileURLToPath(import.meta.url);
+    rootDir = path.resolve(path.dirname(here), "../../spec");
+    const fallbackPkg = path.join(rootDir, "package.json");
+    if (!(await pathExists(fallbackPkg))) {
+      throw new UserError("Cannot locate @aipper/aiws-spec. Install it or run inside the monorepo.", {
+        exitCode: 1,
+      });
+    }
+  }
+
+  const pkg = JSON.parse(await readText(path.join(rootDir, "package.json")));
+  const version = String(pkg.version || "").trim() || "0.0.0";
+  return { rootDir, version };
+}
+
+/**
+ * @param {string} templateId
+ */
+export async function loadTemplate(templateId) {
+  if (!templateId || templateId.includes("..") || templateId.includes("/") || templateId.includes("\\")) {
+    throw new UserError(`Invalid template id: ${templateId}`);
+  }
+
+  const spec = await loadSpecPackage();
+  const templateDir = path.join(spec.rootDir, "templates", templateId);
+  const manifestPath = path.join(templateDir, "manifest.json");
+
+  try {
+    await fs.access(manifestPath);
+  } catch {
+    throw new UserError(`Template not found: ${templateId}`, {
+      details: `Missing: ${manifestPath}`,
+    });
+  }
+
+  const manifest = JSON.parse(await readText(manifestPath));
+  return { templateId, templateDir, manifest, specVersion: spec.version };
+}

package/src/template.js

@@ -0,0 +1,107 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { listFilesRecursive, pathExists, copyFile, readText, writeText, ensureDir } from "./fs.js";
+import { normalizeRel, joinRel } from "./path-utils.js";
+import { normalizeNewlines } from "./hash.js";
+import { extractTemplateBlock, upsertManagedBlock } from "./managed-blocks.js";
+import { UserError } from "./errors.js";
+
+/**
+ * Expand manifest paths, supporting patterns ending with `/**`.
+ *
+ * @param {string} templateDir
+ * @param {string[]} entries
+ */
+export async function expandManifestEntries(templateDir, entries) {
+  /** @type {Set<string>} */
+  const out = new Set();
+
+  for (const raw of entries) {
+    const e = normalizeRel(raw);
+    if (!e) continue;
+    if (e.includes("**")) {
+      const idx = e.indexOf("**");
+      const prefix = e.slice(0, idx).replace(/\/+$/, "");
+      if (!prefix) continue;
+      const files = await listFilesRecursive(templateDir, prefix);
+      for (const f of files) out.add(normalizeRel(f));
+      continue;
+    }
+    out.add(e);
+  }
+
+  return Array.from(out).sort();
+}
+
+/**
+ * @param {string} templateDir
+ * @param {string} relPosix
+ */
+export function templatePath(templateDir, relPosix) {
+  const rel = normalizeRel(relPosix);
+  return path.join(templateDir, ...rel.split("/"));
+}
+
+/**
+ * Copy a template file to workspace, creating parent directories.
+ *
+ * @param {{ templateDir: string, workspaceRoot: string, relPosix: string, chmod?: number }} options
+ */
+export async function copyTemplateFileToWorkspace(options) {
+  const src = templatePath(options.templateDir, options.relPosix);
+  const dest = joinRel(options.workspaceRoot, options.relPosix);
+  if (!(await pathExists(src))) throw new UserError(`Template file missing: ${options.relPosix}`, { details: `Missing: ${src}` });
+  await copyFile(src, dest, typeof options.chmod === "number" ? { chmod: options.chmod } : undefined);
+}
+
+/**
+ * Upsert one or more managed blocks from template into an existing workspace file.
+ *
+ * @param {{ templateDir: string, workspaceRoot: string, fileRel: string, blockIds: string[], insertIfMissing: boolean }} options
+ * @returns {Promise<{ changed: boolean }>}
+ */
+export async function applyManagedBlocksFromTemplate(options) {
+  const fileRel = normalizeRel(options.fileRel);
+  const dest = joinRel(options.workspaceRoot, fileRel);
+  const src = templatePath(options.templateDir, fileRel);
+
+  if (!(await pathExists(src))) throw new UserError(`Template file missing: ${fileRel}`);
+  const templateText = normalizeNewlines(await readText(src));
+
+  if (!(await pathExists(dest))) {
+    await ensureDir(path.dirname(dest));
+    await writeText(dest, templateText);
+    return { changed: true };
+  }
+
+  const currentText = normalizeNewlines(await readText(dest));
+  let nextText = currentText;
+  let anyChanged = false;
+
+  for (const blockId of options.blockIds) {
+    const { blockChunk, innerText } = extractTemplateBlock(templateText, blockId);
+    const res = upsertManagedBlock(nextText, blockId, innerText, {
+      insertIfMissing: options.insertIfMissing,
+      templateBlockChunk: blockChunk,
+    });
+    nextText = res.nextText;
+    if (res.changed) anyChanged = true;
+  }
+
+  if (anyChanged) {
+    await writeText(dest, nextText);
+  }
+  return { changed: anyChanged };
+}
+
+/**
+ * Ensure workspace has a directory.
+ *
+ * @param {string} workspaceRoot
+ * @param {string} relPosix
+ */
+export async function ensureWorkspaceDir(workspaceRoot, relPosix) {
+  const abs = joinRel(workspaceRoot, relPosix);
+  await fs.mkdir(abs, { recursive: true });
+}
+

package/src/workspace.js

@@ -0,0 +1,23 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { pathExists } from "./fs.js";
+import { UserError } from "./errors.js";
+
+/**
+ * @param {string} targetPath
+ * @param {{ create?: boolean }=} options
+ */
+export async function resolveWorkspaceRoot(targetPath, options) {
+  const abs = path.resolve(process.cwd(), targetPath || ".");
+  if (await pathExists(abs)) {
+    const st = await fs.stat(abs);
+    if (!st.isDirectory()) throw new UserError(`Not a directory: ${abs}`);
+    return abs;
+  }
+  if (options?.create) {
+    await fs.mkdir(abs, { recursive: true });
+    return abs;
+  }
+  throw new UserError(`Path does not exist: ${abs}`);
+}
+