@c956180462/awbs 0.0.1

package/docs/USAGE.md

@@ -0,0 +1,294 @@
+# AWBS 使用文档
+
+本文档面向想直接试用 AWBS CLI 的用户。
+
+## 1. 环境要求
+
+需要：
+
+- Node.js `>=24.0.0`
+- Git
+- 一个可以运行 shell 命令的终端
+
+查看版本：
+
+```powershell
+node --version
+git --version
+```
+
+## 2. 安装
+
+从 npm 安装：
+
+```powershell
+npm install -g @c956180462/awbs
+awbs --help
+```
+
+从本地 checkout 安装：
+
+```powershell
+npm install -g .
+awbs --help
+```
+
+开发时直接运行：
+
+```powershell
+node src\cli.ts --help
+npm run awbs -- --help
+```
+
+## 3. 初始化数据库
+
+进入一个项目目录：
+
+```powershell
+mkdir my-awbs-db
+cd my-awbs-db
+```
+
+初始化 AWBS：
+
+```powershell
+awbs init
+```
+
+创建一些业务目录：
+
+```powershell
+mkdir A
+mkdir B
+"read only context" | Set-Content A\context.md
+"first draft" | Set-Content B\draft.md
+```
+
+创建初始 Git commit：
+
+```powershell
+git add .
+git commit -m "initialize database"
+```
+
+如果 Git 还没有用户名和邮箱，需要先配置：
+
+```powershell
+git config user.name "AWBS User"
+git config user.email "awbs@example.test"
+```
+
+## 4. 启动 Authority Session
+
+开发试用时可以用简单字符串。正式应用中，`recoverySecret` 和 `controllerToken` 应由上层应用的非 AI 控制层管理。
+
+```powershell
+'{"recoverySecret":"dev-recovery","controllerToken":"dev-controller"}' |
+  awbs authority session start --control-stdin
+```
+
+检查状态：
+
+```powershell
+awbs authority session status
+```
+
+## 5. 启动 Trusted Chain
+
+```powershell
+'dev-controller' | awbs ledger bootstrap --control-token-stdin
+```
+
+检查 ledger：
+
+```powershell
+awbs ledger inspect
+awbs ledger verify
+```
+
+## 6. 建立索引
+
+```powershell
+awbs index rebuild
+awbs index query
+awbs index query draft
+```
+
+输出来自 `.awbs/index/files.sqlite`。索引可删除重建，不是事实源。
+
+## 7. 写入外部摘要
+
+AWBS 不生成 AI 摘要。摘要由上层业务写入。
+
+```powershell
+awbs summary set B/draft.md --text "A draft document owned by the business layer."
+awbs summary get B/draft.md
+awbs summary list
+awbs index rebuild
+awbs index query business
+```
+
+## 8. 创建工作空间视图
+
+创建一个 workspace：
+
+```powershell
+'dev-controller' |
+  awbs view create --out ..\my-awbs-workspace --read A --write B --control-token-stdin
+```
+
+含义：
+
+- `A` 被投影进 workspace，但只读。
+- `B` 被投影进 workspace，可写。
+- workspace 保持原目录结构。
+
+查看 view：
+
+```powershell
+awbs view inspect <viewId>
+```
+
+## 9. 在 workspace 中工作
+
+修改可写目录：
+
+```powershell
+"second draft" | Set-Content ..\my-awbs-workspace\B\draft.md
+```
+
+如果修改只读目录，例如：
+
+```powershell
+"changed context" | Set-Content ..\my-awbs-workspace\A\context.md
+```
+
+AWBS 不会阻止你在 workspace 中这么做，但 collect 后 changeset 会是 invalid，apply 会拒绝。
+
+## 10. 收集 Changeset
+
+```powershell
+awbs changeset collect --workspace ..\my-awbs-workspace
+```
+
+输出类似：
+
+```text
+Changeset collected: changeset_...
+Status: valid
+```
+
+查看：
+
+```powershell
+awbs changeset inspect <changesetId>
+awbs changeset inspect <changesetId> --json
+```
+
+## 11. 应用 Changeset
+
+```powershell
+'dev-controller' |
+  awbs changeset apply <changesetId> --control-token-stdin
+```
+
+成功后：
+
+- 文件写回 AWBS 数据库。
+- Git 创建 commit。
+- trusted chain 前进。
+- `refs/awbs/trusted` 更新。
+
+## 12. 撤销 View
+
+```powershell
+'dev-controller' |
+  awbs view revoke <viewId> --control-token-stdin
+```
+
+撤销只影响未来 collect/apply，不删除旧 workspace，不删除已提交数据，不改 Git 历史。
+
+## 13. 审计数据库
+
+```powershell
+awbs db audit
+```
+
+它会报告：
+
+- 当前 HEAD。
+- trusted commit。
+- 工作树是否 dirty。
+- 是否存在外部 commit。
+- authority / ledger 是否可验证。
+
+## 14. 从 Trusted Chain 重建干净数据库
+
+如果普通工作区被污染，可以执行：
+
+```powershell
+awbs db clean-rebuild
+```
+
+注意：
+
+- 运行前需要停止 authority session。
+- 原目录会被整体改名为 backup。
+- 干净目录从 trusted commit 重建。
+- backup 不会自动删除。
+
+停止 session：
+
+```powershell
+'dev-controller' | awbs authority session stop --control-token-stdin
+```
+
+## 15. Session 崩溃恢复
+
+如果 session daemon 崩溃，`local.json` 不存在，但 `recovery.seal.json` 仍在：
+
+```powershell
+'dev-recovery' | awbs authority session recover --recovery-secret-stdin
+```
+
+错误 recovery secret 会失败，不会写出伪成功文件。
+
+## 16. 常用命令总览
+
+```text
+awbs init
+awbs index rebuild
+awbs index query [term] [--status active|removed|all] [--json]
+awbs summary set <path> (--text <summary> | --file <file>)
+awbs summary get <path> [--json]
+awbs summary list [--json]
+awbs view create --out <workspace> [--read A] [--write B] --control-token-stdin
+awbs view inspect <viewId> [--json]
+awbs view revoke <viewId> --control-token-stdin
+awbs changeset collect --workspace <workspace>
+awbs changeset inspect <changesetDir|id> [--json]
+awbs changeset apply <changesetDir|id> --control-token-stdin
+awbs ledger bootstrap [--json] --control-token-stdin
+awbs ledger inspect [--json]
+awbs ledger verify [--json]
+awbs db audit [--json]
+awbs db clean-rebuild [--json]
+awbs db backups list [--json]
+awbs authority session start --control-stdin [--json]
+awbs authority session status [--json]
+awbs authority session stop --control-token-stdin [--json]
+awbs authority session recover --recovery-secret-stdin [--json]
+awbs authority verify [--json]
+awbs authority repair-mirrors --control-token-stdin [--json]
+```
+
+## 17. 发布前检查
+
+开发者发布前建议运行：
+
+```powershell
+npm test
+node src\cli.ts --help
+npm pack --dry-run
+git diff --check
+```

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@c956180462/awbs",
+  "version": "0.0.1",
+  "description": "Agent Work Base Space CLI prototype for file-system database workspaces.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "awbs": "bin/awbs.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/a956180462/AWBS.git"
+  },
+  "bugs": {
+    "url": "https://github.com/a956180462/AWBS/issues"
+  },
+  "homepage": "https://github.com/a956180462/AWBS#readme",
+  "keywords": [
+    "agent",
+    "workspace",
+    "filesystem",
+    "git",
+    "cli"
+  ],
+  "files": [
+    "bin",
+    "src",
+    "docs",
+    "AWBS_CORE_DESIGN.md",
+    "AWBS_CURRENT_FEATURES.md",
+    "TASK_001_VIEW_AUTHORITY.md",
+    "TASK_003_AUTHORITY_LEDGER_AND_DB_AUDIT.md",
+    "TASK_004_TRUSTED_AUTHORITY_LAYER.md",
+    "TASK_005_AUTHORITY_SESSION.md",
+    "TASK_006_TRUST_BOUNDARY_HARDENING.md",
+    "TASK_007_TRUSTED_OPERATION_ENTRY.md"
+  ],
+  "scripts": {
+    "awbs": "node src/cli.ts",
+    "test": "node --test --test-concurrency=1 tests/*.test.ts"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}

package/src/adapters/file-summary-store.ts

@@ -0,0 +1,88 @@
+import { readdirSync, readFileSync } from "node:fs";
+import type { IndexKind, SummaryEntry } from "../domain/types.ts";
+import type { FileDatabasePort } from "../ports/file-database.ts";
+import type { SummaryStorePort, SummaryWriteInput } from "../ports/summary-store.ts";
+
+export class FileSummaryStoreAdapter implements SummaryStorePort {
+  private readonly files: FileDatabasePort;
+
+  constructor(files: FileDatabasePort) {
+    this.files = files;
+  }
+
+  readSummaries(summaryFile: string): SummaryEntry[] {
+    if (!this.files.pathExists(summaryFile)) {
+      return [];
+    }
+    const content = this.files.readText(summaryFile).trim();
+    if (!content) {
+      return [];
+    }
+    return content.split(/\r?\n/).map((line) => JSON.parse(line) as SummaryEntry);
+  }
+
+  writeSummary(summaryFile: string, input: SummaryWriteInput): SummaryEntry {
+    const summaries = this.readSummaries(summaryFile);
+    const nextEntry: SummaryEntry = {
+      schemaVersion: 1,
+      path: input.path,
+      kind: input.kind,
+      sha256: input.sha256,
+      commit: input.commit,
+      summary: input.summary,
+      source: "external",
+      updatedAt: new Date().toISOString(),
+      ext: {}
+    };
+
+    const next = summaries.filter((entry) => !(entry.path === nextEntry.path && entry.sha256 === nextEntry.sha256));
+    next.push(nextEntry);
+    next.sort((a, b) => a.path.localeCompare(b.path) || (a.sha256 ?? "").localeCompare(b.sha256 ?? ""));
+    this.files.writeText(summaryFile, next.map((entry) => `${JSON.stringify(entry)}\n`).join(""));
+    return nextEntry;
+  }
+
+  findSummary(summaryFile: string, path: string, sha256: string | null): SummaryEntry | null {
+    const summaries = this.readSummaries(summaryFile).filter((entry) => entry.path === path);
+    const exact = summaries.find((entry) => entry.sha256 === sha256);
+    if (exact) {
+      return exact;
+    }
+    const pathLevel = summaries.find((entry) => entry.sha256 === null);
+    return pathLevel ?? null;
+  }
+
+  fallbackSummary(absPath: string, relPath: string, kind: IndexKind): string {
+    if (kind === "directory") {
+      const count = readdirSync(absPath).length;
+      return `Directory ${relPath} with ${count} item${count === 1 ? "" : "s"}.`;
+    }
+
+    const buffer = readFileSync(absPath);
+    if (!looksText(buffer)) {
+      return `Binary file ${relPath} (${buffer.length} bytes).`;
+    }
+
+    if (buffer.length === 0) {
+      return `Empty text file ${relPath}.`;
+    }
+    return `Text file ${relPath} (${buffer.length} bytes).`;
+  }
+}
+
+function looksText(buffer: Buffer): boolean {
+  if (buffer.length === 0) {
+    return true;
+  }
+  const sample = buffer.subarray(0, Math.min(buffer.length, 4096));
+  let suspicious = 0;
+  for (const byte of sample) {
+    if (byte === 0) {
+      return false;
+    }
+    if (byte < 7 || (byte > 14 && byte < 32)) {
+      suspicious += 1;
+    }
+  }
+  return suspicious / sample.length < 0.05;
+}

package/src/adapters/git-cli.ts

@@ -0,0 +1,107 @@
+import { spawnSync } from "node:child_process";
+import { AwbsError } from "../domain/errors.ts";
+import type { GitCommandResult, GitPort } from "../ports/git.ts";
+
+export class GitCliAdapter implements GitPort {
+  isRepository(root: string): boolean {
+    const result = this.runResult(["rev-parse", "--is-inside-work-tree"], root);
+    return result.status === 0 && result.stdout.trim() === "true";
+  }
+
+  init(root: string): void {
+    this.run(["init"], root);
+  }
+
+  headCommit(root: string): string | null {
+    const result = this.runResult(["rev-parse", "HEAD"], root);
+    return result.status === 0 ? result.stdout.trim() : null;
+  }
+
+  requireHeadCommit(root: string): string {
+    const commit = this.headCommit(root);
+    if (!commit) {
+      throw new AwbsError("Git HEAD is not available. Create an initial commit before running this command.");
+    }
+    return commit;
+  }
+
+  refCommit(root: string, ref: string): string | null {
+    const result = this.runResult(["rev-parse", "--verify", ref], root);
+    return result.status === 0 ? result.stdout.trim() : null;
+  }
+
+  updateRef(root: string, ref: string, commit: string): void {
+    this.run(["update-ref", ref, commit], root);
+  }
+
+  isAncestor(root: string, ancestor: string, descendant: string): boolean {
+    const result = this.runResult(["merge-base", "--is-ancestor", ancestor, descendant], root);
+    return result.status === 0;
+  }
+
+  revList(root: string, range: string): string[] {
+    const output = this.run(["rev-list", "--reverse", range], root).trim();
+    return output ? output.split(/\r?\n/) : [];
+  }
+
+  statusPorcelain(root: string): string {
+    return this.run(["status", "--porcelain", "-uall"], root);
+  }
+
+  addAll(root: string, paths: string[]): void {
+    this.run(["add", "-A", "--", ...paths], root);
+  }
+
+  commit(root: string, message: string): void {
+    this.run(["commit", "-m", message], root);
+  }
+
+  createDetachedWorktree(root: string, path: string, commit: string): void {
+    this.run(["worktree", "add", "--detach", path, commit], root);
+  }
+
+  removeWorktree(root: string, path: string): void {
+    this.run(["worktree", "remove", "--force", path], root);
+  }
+
+  cloneAtCommit(sourceRoot: string, destination: string, commit: string): void {
+    this.run(["clone", "--no-checkout", "--no-hardlinks", sourceRoot, destination], sourceRoot);
+    const sourceRemote = this.runResult(["remote", "get-url", "origin"], sourceRoot);
+    if (sourceRemote.status === 0 && sourceRemote.stdout.trim()) {
+      this.run(["remote", "set-url", "origin", sourceRemote.stdout.trim()], destination);
+    }
+    this.run(["checkout", "--detach", commit], destination);
+  }
+
+  diffNoIndex(baselineRoot: string, workspacePath: string): string {
+    const result = spawnSync("git", ["diff", "--no-index", "--binary", "--no-color", "--", baselineRoot, workspacePath], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    if (result.status === 0 || result.status === 1) {
+      return result.stdout ?? "";
+    }
+    return `git diff --no-index failed:\n${result.stderr ?? ""}`;
+  }
+
+  private run(args: string[], cwd: string): string {
+    const result = this.runResult(args, cwd);
+    if (result.status !== 0) {
+      throw new AwbsError(`git ${args.join(" ")} failed:\n${result.stderr || result.stdout}`);
+    }
+    return result.stdout;
+  }
+
+  private runResult(args: string[], cwd: string): GitCommandResult {
+    const result = spawnSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    return {
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+      status: result.status
+    };
+  }
+}