tgo-wiki 0.1.0

package/docs/v0-acceptance.md

@@ -0,0 +1,105 @@
+# Agent Wiki v0 Acceptance Gate
+
+Date: 2026-06-11
+
+## Purpose
+
+This document defines the local acceptance gate for the v0 MCP-first Agent Wiki slice. Run this gate before treating v0 as ready for handoff, release, or follow-on feature work.
+
+v0 is now historical scope. For the current v2 release gate, use [v2-acceptance.md](./v2-acceptance.md), which extends the v1 document ingestion, source read, and fast-forward publish baseline with web ingestion.
+
+The gate is intentionally black-box at the outer edge: the dedicated black-box package starts the public CLI and talks to the MCP server over stdio JSON-RPC. It must not import `@tgo-wiki/core`, `@tgo-wiki/server`, or internal service modules.
+
+## Required Commands
+
+For historical v0 verification, run from the repository root:
+
+```bash
+bun install
+bun run verify:v0
+```
+
+Acceptance requires every command to exit with code 0.
+
+At the time of v0 delivery, `bun run release:check` was the single local release-readiness gate and expanded to:
+
+```bash
+bun run verify:v0 && bun run smoke:pack && bun pm pack --dry-run
+```
+
+`bun run verify:v0` runs the full local v0 gate:
+
+```bash
+bun run check && bun run test:blackbox
+```
+
+`bun run check` runs the default unit and integration test suite for `packages/core` and `packages/server`, then runs `tsc --noEmit`.
+
+`bun run test:blackbox` runs the independent `packages/blackbox-tests` package. This suite is explicit by design and is not part of the default `bun run test` command.
+
+`bun run smoke:pack` creates a tarball with `bun pm pack`, installs that tarball into a temporary consumer project, and exercises the installed `tgo-wiki` bin for CLI init/status plus MCP `initialize` and `tools/list`.
+
+`bun run smoke:cli` runs the same CLI/MCP flow through a faster `file:` install. It is useful during local development, while `smoke:pack` is the release-readiness gate.
+
+The GitHub Actions workflow at `.github/workflows/v0-acceptance.yml` runs `bun run check`, `bun run test:blackbox`, and `bun run smoke:pack` as separate jobs.
+
+## Historical v0 Black-Box Coverage
+
+The black-box package must verify these public behaviors through `packages/server/src/cli.ts` only:
+
+- `tgo-wiki init --workspace <path>` creates a usable local workspace.
+- `tgo-wiki status --workspace <path>` reports the stable branch, clean status, and session count.
+- MCP `initialize` and `tools/list` expose exactly the v0 tool surface.
+- `wiki_read` reads stable Markdown content.
+- `vfs_exec` executes allowed read-only VFS commands.
+- A writer can complete the session flow:
+  - `wiki_session_start`
+  - `wiki_session_patch`
+  - `wiki_session_validate`
+  - `wiki_session_diff`
+  - `wiki_session_commit`
+- A committed session branch does not mutate stable content.
+- A reader receives permission errors for every writer-only session tool.
+- Read tools reject unsupported refs and path traversal attempts.
+- Session patch rejects unsafe paths and unified patch payloads.
+- Invalid Markdown produces validation errors and cannot be committed.
+- Empty session commits return a typed tool error.
+
+## v0 Scope Guard
+
+The following tools are intentionally out of scope for v0 and must not appear in `tools/list`:
+
+- `wiki_publish_session`
+- `wiki_rollback`
+- `wiki_search`
+- document ingestion tools
+- web ingestion tools
+- QA or semantic search tools
+
+`publisher` and `admin` roles may exist as higher-privilege roles for the implemented read/write tools, but v0 must not expose publish or rollback behavior.
+
+v1 historically superseded this guard by adding document ingestion, source read tools, and `wiki_publish_session`. v2 is the current release gate and adds web ingestion; see [v2-acceptance.md](./v2-acceptance.md) for the active public behavior list.
+
+## Manual Spot Check
+
+Use this only when changing CLI startup, MCP transport, or packaging:
+
+```bash
+workspace="$(mktemp -d)"
+bun packages/server/src/cli.ts init --workspace "$workspace"
+bun packages/server/src/cli.ts status --workspace "$workspace"
+bun packages/server/src/cli.ts mcp --workspace "$workspace" --role reader
+```
+
+For MCP manual checks, send `initialize`, `notifications/initialized`, and `tools/list` messages over stdio JSON-RPC. Prefer the automated black-box package for repeatable verification.
+
+## Failure Policy
+
+If any command in the required gate fails:
+
+1. Do not merge or hand off the change.
+2. Identify whether the failure is in unit/integration tests, type checking, or black-box behavior.
+3. Fix the smallest root cause.
+4. Re-run the full required command set from this document.
+
+Black-box failures should be treated as public contract failures unless investigation proves the test is asserting behavior outside v0 scope.

package/docs/v0-delivery-checklist.md

@@ -0,0 +1,57 @@
+# Agent Wiki v0 Delivery Checklist
+
+Date: 2026-06-12
+
+## v0 Scope
+
+This checklist summarizes the historical v0 handoff and delivery state for the MCP-first v0 slice.
+
+v0 is historical scope. v1 superseded and extended it with document ingestion, source reads, and fast-forward publish. v2 is the current release gate and adds web ingestion; use [v2-acceptance.md](./v2-acceptance.md) for current acceptance.
+
+Implemented:
+
+- Local wiki workspace initialization and status inspection.
+- MCP stdio server startup for reader and writer roles.
+- Stable wiki reads through `wiki_read`, `wiki_channel_status`, and read-only `vfs_exec`.
+- Isolated writer sessions with start, full-content patch, validate, diff, and commit.
+- Reader/writer permission enforcement.
+- Markdown validation for frontmatter, H1, path safety, and links.
+- Public black-box coverage through CLI and MCP stdio JSON-RPC.
+- Packed tarball smoke coverage for the installed `tgo-wiki` bin.
+
+Deferred:
+
+- `publish/rollback` behavior and tools.
+- Search, QA, document ingestion, and web ingestion.
+- Remote git, pull request integration, and web UI.
+
+## Required Verification
+
+For the current release gate, run:
+
+```bash
+bun install --frozen-lockfile
+bun run release:check
+```
+
+For v0 delivery, `bun run release:check` ran:
+
+```bash
+bun run verify:v0 && bun run smoke:pack && bun pm pack --dry-run
+```
+
+The release gate must report:
+
+- default unit/integration tests passing;
+- independent black-box tests passing;
+- packed tarball smoke passing through the installed `.bin/tgo-wiki`;
+- pack dry-run listing the expected narrow file set.
+
+## Handoff Notes
+
+- Use `docs/mcp-usage.md` for MCP client setup and tool examples.
+- Use `docs/v2-acceptance.md` as the current release acceptance policy.
+- Use `docs/v1-acceptance.md` as the historical v1 acceptance policy.
+- Use `docs/v0-acceptance.md` as the historical v0 acceptance policy.
+- Use `CHANGELOG.md` as the release-note draft source.
+- Keep v0 publish/rollback deferral notes historical; v1 adds ff-only session publish while rollback remains deferred.

package/docs/v1-acceptance.md

@@ -0,0 +1,39 @@
+# Agent Wiki v1 Acceptance Gate
+
+Date: 2026-06-13
+
+## Purpose
+
+This document defines the historical v1 release acceptance gate for Agent Wiki. For the current v2 release gate, use [v2-acceptance.md](./v2-acceptance.md). v1 adds document ingestion on top of the v0 local git, worktree, session, validation, commit, and MCP surface.
+
+The gate verifies that agents can upload raw document blobs into workspace state, parse those documents into git-tracked source files inside an isolated session worktree, cite those sources from wiki page frontmatter, commit the combined wiki/source changes, and fast-forward publish the clean committed session to stable with the appropriate role.
+
+The v1.1 slice supports direct ingestion for `application/pdf`, `text/markdown`, `text/x-markdown`, and `text/plain`.
+
+## Required Commands
+
+Run from the repository root:
+
+```bash
+bun install --frozen-lockfile
+bun run release:check
+```
+
+Acceptance requires every command to exit with code 0.
+
+## Required Public Behaviors
+
+- `wiki_publish_session` fast-forwards stable for committed clean sessions.
+- `document_upload` stores raw blobs under workspace state, not git.
+- `document_upload` accepts PDF, Markdown, and plain text documents.
+- `document_parse` writes `sources/<document_id>/raw.md` and `metadata.json` into the session worktree.
+- `document_parse` preserves Markdown uploads as raw Markdown and wraps plain text uploads in readable Markdown.
+- Workspace config can enable command-backed parsers with explicit supported MIME types.
+- Command parser stdout is written as source raw Markdown; command failures return `parse_failed`.
+- `source_list` and `source_read` read stable and session refs.
+- `wiki_session_patch` rejects `sources/**` with `source_write_denied`.
+- `wiki_session_validate` accepts wiki pages with valid `sources` frontmatter and rejects missing source IDs.
+- `wiki_session_commit` commits both wiki pages and source files.
+- Reader can read sources but cannot upload or parse documents.
+- Writer can upload and parse but cannot publish.
+- Publisher and admin can publish.

package/docs/v2-acceptance.md

@@ -0,0 +1,165 @@
+# Agent Wiki v2 Acceptance Gate
+
+Date: 2026-06-13
+
+## Purpose
+
+This document defines the current release acceptance gate for Agent Wiki v2. v2 adds static web ingestion on top of the v1 local git, worktree, session, validation, source, commit, and publish surface.
+
+The gate verifies that agents can fetch one HTML page into an isolated session, read the generated source, cite the returned source id from wiki page frontmatter, validate and commit the combined wiki/source changes, fast-forward publish the clean committed session to stable, and read the published source from stable.
+
+## Required Commands
+
+Run from the repository root:
+
+```bash
+bun install --frozen-lockfile
+bun run release:check
+```
+
+Acceptance requires every command to exit with code 0.
+
+## Required Public Behaviors
+
+- `web_fetch` is available to publisher and admin roles only.
+- `web_fetch` fetches exactly one absolute public `http:` or `https:` URL with the static fetcher.
+- `web_fetch` rejects private, loopback, link-local, multicast, and reserved network targets by default, including redirects to those targets. Workspace config may explicitly allow private hosts with `web.allowedPrivateHosts`.
+- `web_fetch` stores the original HTML blob outside git under `state/web/blobs/sha256/<sha256>`.
+- `web_fetch` writes `sources/<source_id>/raw.md` and `sources/<source_id>/metadata.json` into the session worktree.
+- `web_fetch` returns `source_id`, `version`, `raw_markdown_path`, `metadata_path`, `html_blob_sha256`, `status`, optional `title`, and `warnings`.
+- Existing source APIs expose the generated raw Markdown and metadata. `source_read` still accepts `document_id`; pass the returned web `source_id` as that value.
+- `source_list` and `source_read` read web sources from stable and session refs.
+- `wiki_session_patch` can cite the returned source id in page `sources` frontmatter.
+- `wiki_session_validate` accepts valid web source citations and rejects missing source IDs.
+- `wiki_session_commit` commits wiki pages and generated source files together.
+- `wiki_publish_session` fast-forwards stable for committed clean sessions.
+- Reader and writer roles can read permitted sources but cannot call `web_fetch`.
+
+## Required Flow
+
+Start the MCP server with `--role publisher` or `--role admin`, then initialize MCP.
+
+```text
+wiki_session_start
+web_fetch
+source_read with ref = session_id
+wiki_session_patch with frontmatter.sources citing returned source_id
+wiki_session_validate
+wiki_session_diff
+wiki_session_commit
+wiki_publish_session as publisher/admin
+source_read from stable
+```
+
+For separated duties, a writer can start the session, patch, validate, diff, and commit. A publisher or admin performs `web_fetch` and the final publish step.
+
+## `web_fetch` Example
+
+Input:
+
+```json
+{
+  "session_id": "SESSION_ID",
+  "url": "https://example.com/docs"
+}
+```
+
+Result:
+
+```json
+{
+  "source_id": "web_20260613_ab12cd34ef567890",
+  "version": 1,
+  "raw_markdown_path": "sources/web_20260613_ab12cd34ef567890/raw.md",
+  "metadata_path": "sources/web_20260613_ab12cd34ef567890/metadata.json",
+  "html_blob_sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+  "status": "fetched",
+  "title": "Example Docs",
+  "warnings": []
+}
+```
+
+The original HTML bytes for this result are stored outside git at:
+
+```text
+state/web/blobs/sha256/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+```
+
+The session worktree receives:
+
+```text
+sources/web_20260613_ab12cd34ef567890/raw.md
+sources/web_20260613_ab12cd34ef567890/metadata.json
+```
+
+## Source Read Example
+
+Use the returned `source_id` as `document_id` when reading through the existing source API:
+
+```json
+{
+  "document_id": "web_20260613_ab12cd34ef567890",
+  "ref": "SESSION_ID"
+}
+```
+
+Result shape:
+
+```json
+{
+  "document_id": "web_20260613_ab12cd34ef567890",
+  "ref": "SESSION_ID",
+  "metadata": {
+    "documentId": "web_20260613_ab12cd34ef567890",
+    "version": 1,
+    "sourceType": "web",
+    "url": "https://example.com/docs",
+    "finalUrl": "https://example.com/docs",
+    "title": "Example Docs",
+    "contentType": "text/html; charset=utf-8",
+    "statusCode": 200,
+    "htmlBlobSha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+    "rawMarkdownPath": "sources/web_20260613_ab12cd34ef567890/raw.md",
+    "fetcher": {
+      "name": "static-fetch",
+      "version": "1.0.0"
+    },
+    "fetchMetadata": {
+      "htmlBytes": 1234,
+      "markdownBytes": 567
+    },
+    "status": "fetched"
+  },
+  "raw_markdown": "# Example Docs\n\n> Source web page: https://example.com/docs\n> Final URL: https://example.com/docs\n> Fetched at: 2026-06-13T00:00:00.000Z\n> Fetcher: static-fetch\n\n..."
+}
+```
+
+## Wiki Citation Example
+
+Patch a normal wiki page with frontmatter that cites the fetched source:
+
+```markdown
+---
+title: "Example Docs"
+summary: "Notes derived from the fetched web source."
+tags: ["web", "imported"]
+updated: "2026-06-13"
+sources:
+  - web_20260613_ab12cd34ef567890
+---
+
+# Example Docs
+
+The published page content should cite the fetched source id in frontmatter.
+```
+
+## Stable Read Requirement
+
+After `wiki_session_commit` and `wiki_publish_session`, `source_read` with `ref: "stable"` must return the same source metadata and raw Markdown for the web source:
+
+```json
+{
+  "document_id": "web_20260613_ab12cd34ef567890",
+  "ref": "stable"
+}
+```

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "tgo-wiki",
+  "version": "0.1.0",
+  "description": "Local git-backed Agent Wiki MCP server and CLI.",
+  "type": "module",
+  "homepage": "https://github.com/tgoai/tgo-wiki#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tgoai/tgo-wiki.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tgoai/tgo-wiki/issues"
+  },
+  "keywords": [
+    "agent",
+    "bun",
+    "cli",
+    "knowledge-base",
+    "mcp",
+    "wiki"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "bin": {
+    "tgo-wiki": "./packages/server/src/cli.ts"
+  },
+  "files": [
+    "packages/core/src/**/*.ts",
+    "packages/server/src/**/*.ts",
+    "!packages/**/*.test.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/mcp-usage.md",
+    "docs/v2-acceptance.md",
+    "docs/v1-acceptance.md",
+    "docs/v0-acceptance.md",
+    "docs/v0-delivery-checklist.md"
+  ],
+  "scripts": {
+    "test": "bun test packages/core/src packages/server/src",
+    "test:blackbox": "bun test packages/blackbox-tests/src",
+    "typecheck": "tsc --noEmit",
+    "check": "bun run test && tsc --noEmit",
+    "verify:v0": "bun run check && bun run test:blackbox",
+    "verify:v1": "bun run check && bun run test:blackbox",
+    "verify:v2": "bun run check && bun run test:blackbox",
+    "example:mcp": "bun examples/mcp-stdio-client.ts",
+    "smoke:cli": "bun scripts/smoke-cli.ts",
+    "smoke:pack": "bun scripts/smoke-cli.ts --source pack",
+    "release:check": "bun run verify:v2 && bun run smoke:pack && bun pm pack --dry-run",
+    "prepublishOnly": "bun run release:check"
+  },
+  "dependencies": {
+    "@cfworker/json-schema": "^4.1.1",
+    "@modelcontextprotocol/server": "^2.0.0-alpha.2",
+    "gray-matter": "^4.0.3",
+    "pdf-parse": "^2.4.5",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "bun-types": "^1.3.14",
+    "typescript": "^6.0.3"
+  }
+}

package/packages/core/src/config/config-loader.ts

@@ -0,0 +1,109 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { defaultConfig, type DocumentParserConfig, type WikiConfig } from "./defaults.js";
+import type { WorkspacePaths } from "./workspace-resolver.js";
+import { WikiError } from "../errors.js";
+
+type ParsedWikiConfig = Partial<Omit<WikiConfig, "documents">> & {
+  documents?: Partial<Omit<WikiConfig["documents"], "parsers">> & {
+    parsers?: Record<string, DocumentParserConfig>;
+  };
+  web?: Partial<WikiConfig["web"]>;
+};
+
+export async function loadConfig(paths: WorkspacePaths): Promise<WikiConfig> {
+  const configPath = path.join(paths.statePath, "config.json");
+
+  try {
+    const raw = await readFile(configPath, "utf8");
+    const parsed = JSON.parse(raw) as ParsedWikiConfig;
+    assertOptionalConfigObject("web", parsed.web);
+
+    const merged = {
+      ...defaultConfig,
+      ...parsed,
+      channels: {
+        ...defaultConfig.channels,
+        ...parsed.channels,
+        stable: {
+          ...defaultConfig.channels.stable,
+          ...parsed.channels?.stable
+        }
+      },
+      vfs: {
+        ...defaultConfig.vfs,
+        ...parsed.vfs
+      },
+      validation: {
+        ...defaultConfig.validation,
+        ...parsed.validation
+      },
+      documents: {
+        ...defaultConfig.documents,
+        ...parsed.documents,
+        parsers: mergeParserConfigs(defaultConfig.documents.parsers, parsed.documents?.parsers)
+      },
+      web: {
+        ...defaultConfig.web,
+        ...parsed.web
+      }
+    };
+
+    validateConfig(merged);
+    return merged;
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return defaultConfig;
+    }
+
+    throw error;
+  }
+}
+
+function mergeParserConfigs(
+  defaultParsers: Record<string, DocumentParserConfig>,
+  configuredParsers: Record<string, DocumentParserConfig> = {}
+): Record<string, DocumentParserConfig> {
+  const merged = { ...defaultParsers };
+
+  for (const [parserName, configuredParser] of Object.entries(configuredParsers)) {
+    merged[parserName] = {
+      ...defaultParsers[parserName],
+      ...configuredParser
+    };
+  }
+
+  return merged;
+}
+
+function validateConfig(config: WikiConfig): void {
+  assertPositiveInteger("web.requestTimeoutMs", config.web.requestTimeoutMs, 120000);
+  assertPositiveInteger("web.maxResponseBytes", config.web.maxResponseBytes, 52428800);
+
+  if (
+    !Array.isArray(config.web.allowedPrivateHosts) ||
+    config.web.allowedPrivateHosts.some(host => typeof host !== "string" || host.trim().length === 0)
+  ) {
+    throw new WikiError("validation_failed", "web.allowedPrivateHosts must be an array of non-empty host strings");
+  }
+}
+
+function assertOptionalConfigObject(fieldName: string, value: unknown): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new WikiError("validation_failed", `${fieldName} must be an object`);
+  }
+}
+
+function assertPositiveInteger(fieldName: string, value: unknown, max: number): void {
+  if (!Number.isSafeInteger(value) || typeof value !== "number" || value <= 0) {
+    throw new WikiError("validation_failed", `${fieldName} must be a positive integer`);
+  }
+
+  if (value > max) {
+    throw new WikiError("validation_failed", `${fieldName} must be <= ${max}`);
+  }
+}

package/packages/core/src/config/defaults.ts

@@ -0,0 +1,74 @@
+export type WikiConfig = {
+  version: 1;
+  wikiRoot: string;
+  stableBranch: string;
+  repoManagementBranch: string;
+  sessionBranchPrefix: string;
+  channels: {
+    stable: {
+      branch: string;
+      worktree: string;
+    };
+  };
+  vfs: {
+    allowedCommands: string[];
+  };
+  validation: {
+    requireH1: boolean;
+    requireExistingInternalLinks: boolean;
+  };
+  documents: {
+    defaultParser: string;
+    parsers: Record<string, DocumentParserConfig>;
+  };
+  web: {
+    requestTimeoutMs: number;
+    maxResponseBytes: number;
+    allowedPrivateHosts: string[];
+  };
+};
+
+export type DocumentParserConfig = {
+  enabled: boolean;
+  command?: string;
+  supportedMimeTypes?: string[];
+  version?: string;
+  timeoutMs?: number;
+};
+
+export const defaultConfig: WikiConfig = {
+  version: 1,
+  wikiRoot: "wiki",
+  stableBranch: "wiki/stable",
+  repoManagementBranch: "wiki/repo",
+  sessionBranchPrefix: "wiki/session/",
+  channels: {
+    stable: {
+      branch: "wiki/stable",
+      worktree: "worktrees/stable"
+    }
+  },
+  vfs: {
+    allowedCommands: ["pwd", "ls", "find", "cat", "grep", "head", "tail", "wc", "tree"]
+  },
+  validation: {
+    requireH1: true,
+    requireExistingInternalLinks: true
+  },
+  documents: {
+    defaultParser: "pdf-text",
+    parsers: {
+      "pdf-text": {
+        enabled: true
+      },
+      "text-markdown": {
+        enabled: true
+      }
+    }
+  },
+  web: {
+    requestTimeoutMs: 15000,
+    maxResponseBytes: 5242880,
+    allowedPrivateHosts: []
+  }
+};

package/packages/core/src/config/workspace-resolver.ts

@@ -0,0 +1,40 @@
+import path from "node:path";
+
+export type WorkspacePaths = {
+  workspaceRoot: string;
+  repoPath: string;
+  statePath: string;
+  sessionsStatePath: string;
+  documentsStatePath: string;
+  documentBlobsPath: string;
+  webStatePath: string;
+  webBlobsPath: string;
+  pendingDocumentsPath: string;
+  worktreesPath: string;
+  stableWorktreePath: string;
+  sessionsWorktreePath: string;
+  wikiRootName: "wiki";
+};
+
+export function resolveWorkspacePaths(workspaceRoot: string): WorkspacePaths {
+  const root = path.resolve(workspaceRoot);
+  const statePath = path.join(root, "state");
+  const documentsStatePath = path.join(statePath, "documents");
+  const worktreesPath = path.join(root, "worktrees");
+
+  return {
+    workspaceRoot: root,
+    repoPath: path.join(root, "repo"),
+    statePath,
+    sessionsStatePath: path.join(statePath, "sessions"),
+    documentsStatePath,
+    documentBlobsPath: path.join(documentsStatePath, "blobs", "sha256"),
+    webStatePath: path.join(statePath, "web"),
+    webBlobsPath: path.join(statePath, "web", "blobs", "sha256"),
+    pendingDocumentsPath: path.join(documentsStatePath, "pending"),
+    worktreesPath,
+    stableWorktreePath: path.join(worktreesPath, "stable"),
+    sessionsWorktreePath: path.join(worktreesPath, "sessions"),
+    wikiRootName: "wiki"
+  };
+}