@aipper/aiws 0.0.1

package/README.md

@@ -0,0 +1,54 @@
+# @aipper/aiws
+
+AI Workspace CLI：`aiws init/update/validate/rollback`。
+
+真值来源（SSOT）：`@aipper/aiws-spec`（模板与契约在 `packages/spec/`）。
+
+需求真值：仓库根 `REQUIREMENTS.md`（TOOLING-001B）。
+
+开发期最小验证（本仓库内）：
+- `node packages/aiws/bin/aiws.js --help`
+
+Codex repo skills（推荐）：
+- `aiws init .` 会生成 `.agents/skills/`（随仓库共享）
+- 在 Codex 中可显式调用（示例）：`$ws-preflight` / `$ws-plan` / `$ws-dev` / `$ws-review` / `$ws-commit`
+
+Codex 全局 skills（推荐；可选）：
+- 安装到 `~/.codex/skills/`（或 `$CODEX_HOME/skills`）：`aiws codex install-skills`
+- 预演（不写入）：`aiws codex install-skills --dry-run`
+- 状态检查：`aiws codex status-skills`
+- 卸载（仅移除 AIWS 托管 skills；会备份）：`aiws codex uninstall-skills`
+- 本仓库内可复现验证（不写入 home）：`CODEX_HOME="$(mktemp -d)" node packages/aiws/bin/aiws.js codex install-skills`
+
+Codex 全局 prompts（遗留；deprecated）：
+- 安装到 `~/.codex/prompts/`（或 `$CODEX_HOME/prompts`）：`aiws codex install-prompts`
+- 预演（不写入）：`aiws codex install-prompts --dry-run`
+- 状态检查：`aiws codex status`
+- 卸载（仅移除 AIWS 托管 prompts；会备份）：`aiws codex uninstall-prompts`
+- 本仓库内可复现验证（不写入 home）：`CODEX_HOME="$(mktemp -d)" node packages/aiws/bin/aiws.js codex install-prompts`
+
+Git hooks 门禁（推荐）：
+- 启用（会自动补齐 `.githooks/*`，并设置 `core.hooksPath=.githooks`）：`aiws hooks install .`
+- 查看状态：`aiws hooks status .`
+- 证据落盘（可选）：`AIWS_VALIDATE_STAMP=1 aiws validate .` 会写入 `.agentdocs/tmp/aiws-validate/*.json`（`.agentdocs/` 被 `.gitignore` 忽略）
+
+Change 工作流（脱离 dotfiles）：
+- 创建工件：`aiws change new <change-id>`（生成 `changes/<change-id>/{proposal,tasks,design}.md` 与 `.ws-change.json`）
+- 切分支并初始化：`aiws change start <change-id> [--hooks]`
+- 进度/建议：`aiws change list` / `aiws change status <change-id>` / `aiws change next <change-id>`
+- 同步真值基线：`aiws change sync <change-id>`
+- 严格校验：`aiws change validate <change-id> --strict`（在你把 `WS:TODO` 与归因补齐前，预期会失败）
+- 归档：`aiws change archive <change-id>`
+
+本仓库内可复现验证（不污染本仓库）：
+```bash
+repo_root="$(pwd)"
+tmpdir="$(mktemp -d)"
+cd "$tmpdir"
+git init
+node "$repo_root/packages/aiws/bin/aiws.js" init .
+node "$repo_root/packages/aiws/bin/aiws.js" change new demo-change --no-design
+node "$repo_root/packages/aiws/bin/aiws.js" change list
+node "$repo_root/packages/aiws/bin/aiws.js" change sync demo-change
+node "$repo_root/packages/aiws/bin/aiws.js" change validate demo-change --strict
+```

package/bin/aiws.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { cliMain } from "../src/cli.js";
+import { UserError } from "../src/errors.js";
+
+try {
+  const exitCode = await cliMain(process.argv.slice(2));
+  process.exitCode = exitCode;
+} catch (error) {
+  if (error instanceof UserError) {
+    process.exitCode = error.exitCode;
+    if (error.message) console.error(error.message);
+    if (error.details) console.error(error.details);
+  } else {
+    const e = error instanceof Error ? error : new Error(String(error));
+    process.exitCode = 1;
+    console.error(e.stack || e.message);
+  }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@aipper/aiws",
+  "version": "0.0.1",
+  "description": "AI Workspace CLI (init/update/validate) for Claude Code / OpenCode / Codex / iFlow.",
+  "type": "module",
+  "bin": {
+    "aiws": "./bin/aiws.js"
+  },
+  "dependencies": {
+    "@aipper/aiws-spec": "0.0.1"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/aiws-package.js

@@ -0,0 +1,15 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readText } from "./fs.js";
+
+/**
+ * @returns {Promise<{ rootDir: string, version: string }>}
+ */
+export async function loadAiwsPackage() {
+  const here = fileURLToPath(import.meta.url);
+  const rootDir = path.resolve(path.dirname(here), "..");
+  const pkg = JSON.parse(await readText(path.join(rootDir, "package.json")));
+  const version = String(pkg.version || "").trim() || "0.0.0";
+  return { rootDir, version };
+}
+

package/src/backup.js

@@ -0,0 +1,149 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ensureDir, pathExists } from "./fs.js";
+import { joinRel, normalizeRel } from "./path-utils.js";
+import { UserError } from "./errors.js";
+
+/**
+ * @param {Date} d
+ */
+export function formatBackupTimestamp(d) {
+  return d.toISOString().replace(/\.\d{3}Z$/, "Z").replaceAll(":", "-");
+}
+
+export class BackupSession {
+  /**
+   * @param {{ workspaceRoot: string, operation: "init" | "update" }} options
+   */
+  constructor(options) {
+    this.workspaceRoot = options.workspaceRoot;
+    this.operation = options.operation;
+    this.timestamp = formatBackupTimestamp(new Date());
+    this.backupRoot = path.join(this.workspaceRoot, ".aiws", "backups", this.timestamp);
+    /** @type {Map<string, { existed: boolean, mode: number | null }>} */
+    this.files = new Map();
+    this._prepared = false;
+  }
+
+  async _prepare() {
+    if (this._prepared) return;
+    await ensureDir(this.backupRoot);
+    this._prepared = true;
+  }
+
+  /**
+   * Record a file before modification.
+   *
+   * For update: record both existing and missing files (for rollback deletions).
+   * For init: typically record only existing files that will be modified.
+   *
+   * @param {string} relPosix
+   * @param {{ recordMissing?: boolean }=} options
+   */
+  async recordFile(relPosix, options) {
+    const rel = normalizeRel(relPosix);
+    if (this.files.has(rel)) return;
+
+    const abs = joinRel(this.workspaceRoot, rel);
+    const exists = await pathExists(abs);
+    if (!exists) {
+      if (options?.recordMissing) {
+        this.files.set(rel, { existed: false, mode: null });
+      }
+      return;
+    }
+
+    const st = await fs.stat(abs);
+    if (!st.isFile()) {
+      if (options?.recordMissing) this.files.set(rel, { existed: false, mode: null });
+      return;
+    }
+
+    await this._prepare();
+    const dest = joinRel(this.backupRoot, rel);
+    await ensureDir(path.dirname(dest));
+    await fs.copyFile(abs, dest);
+    try {
+      await fs.chmod(dest, st.mode & 0o777);
+    } catch {
+      // ignore chmod errors
+    }
+
+    this.files.set(rel, { existed: true, mode: st.mode & 0o777 });
+  }
+
+  /**
+   * @param {{ extra?: any }=} options
+   */
+  async finalize(options) {
+    if (!this._prepared && this.files.size === 0) return null;
+    await this._prepare();
+    const meta = {
+      operation: this.operation,
+      timestamp: this.timestamp,
+      created_at: new Date().toISOString(),
+      files: Array.from(this.files.entries()).map(([p, v]) => ({ path: p, existed: v.existed, mode: v.mode })),
+      extra: options?.extra ?? null,
+    };
+    await fs.writeFile(path.join(this.backupRoot, "backup.json"), JSON.stringify(meta, null, 2) + "\n", "utf8");
+    return this.backupRoot;
+  }
+}
+
+/**
+ * @param {string} workspaceRoot
+ * @param {string} stamp
+ * @returns {Promise<string>} backup root dir
+ */
+export async function resolveBackupRoot(workspaceRoot, stamp) {
+  const backupsRoot = path.join(workspaceRoot, ".aiws", "backups");
+  if (stamp === "latest") {
+    if (!(await pathExists(backupsRoot))) throw new UserError("No backups found.");
+    const entries = await fs.readdir(backupsRoot, { withFileTypes: true });
+    const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+    const latest = dirs[dirs.length - 1];
+    if (!latest) throw new UserError("No backups found.");
+    return path.join(backupsRoot, latest);
+  }
+
+  const target = path.join(backupsRoot, stamp);
+  if (!(await pathExists(target))) {
+    throw new UserError(`Backup not found: ${stamp}`, { details: `Missing: ${target}` });
+  }
+  return target;
+}
+
+/**
+ * @param {string} workspaceRoot
+ * @param {string} backupRoot
+ */
+export async function rollbackFromBackup(workspaceRoot, backupRoot) {
+  const metaPath = path.join(backupRoot, "backup.json");
+  if (!(await pathExists(metaPath))) {
+    throw new UserError("backup.json not found; cannot rollback safely.", { details: `Missing: ${metaPath}` });
+  }
+  const meta = JSON.parse(await fs.readFile(metaPath, "utf8"));
+  const files = Array.isArray(meta.files) ? meta.files : [];
+  for (const f of files) {
+    const rel = normalizeRel(String(f.path || ""));
+    if (!rel) continue;
+    const dest = joinRel(workspaceRoot, rel);
+    if (f.existed) {
+      const src = joinRel(backupRoot, rel);
+      await ensureDir(path.dirname(dest));
+      await fs.copyFile(src, dest);
+      if (typeof f.mode === "number") {
+        try {
+          await fs.chmod(dest, f.mode);
+        } catch {
+          // ignore chmod errors
+        }
+      }
+    } else {
+      if (await pathExists(dest)) {
+        await fs.rm(dest, { force: true });
+      }
+    }
+  }
+}
+