tgo-wiki 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## [0.1.0] - 2026-06-13
+
+### Added
+
+- MCP-first Agent Wiki v0 slice with local git-backed workspace initialization, status, stable reads, and writer sessions.
+- Reader and writer role enforcement for the v0 MCP tool surface.
+- Markdown validation for frontmatter, headings, links, and wiki path safety.
+- Independent black-box package that exercises the public CLI and MCP stdio JSON-RPC surface.
+- Packed tarball smoke via `bun run smoke:pack`.
+- Release-readiness gate via `bun run release:check`.
+- v1 document ingestion MCP tools for upload, parse, source listing, and source reading.
+- v1.1 direct Markdown and plain text document ingestion through the existing document tools.
+- v1.1 command-backed document parser configuration for local parser plugins.
+- Git-tracked `sources/` raw Markdown with state-stored source blobs.
+- Optional wiki page `sources` frontmatter validation.
+- ff-only session publish for publisher and admin roles.
+- v2 web ingestion MVP with `web_fetch`, state-stored HTML blobs, generated web sources, source citations, commit, publish, and stable source reads.
+- Publish-ready npm package metadata for installing the `tgo-wiki` CLI from the registry.
+
+### Verification
+
+- `bun run release:check`
+- `bun run verify:v0`
+- `bun run smoke:pack`
+
+### Deferred
+
+- Rollback tooling.
+- Search and QA tooling
+- Remote git, pull request integration, and web UI

package/README.md

@@ -0,0 +1,255 @@
+# TGO Wiki
+
+TGO Wiki is a Bun-first TypeScript implementation of the Agent Wiki MCP surface. It gives an agent a local git-backed wiki workspace, stable read tools, isolated edit sessions for Markdown changes, v1 document ingestion that turns uploaded source documents into git-tracked wiki sources, and v2 web ingestion that fetches static HTML pages into citable sources.
+
+## v2 Current Scope
+
+v2 extends the v1 local git/worktree/session/validation/commit/publish/source surface with static web ingestion:
+
+- Fetch one public `http:` or `https:` HTML page into an open session with `web_fetch` as `publisher` or `admin`.
+- Store original HTML blobs outside git under workspace state.
+- Convert fetched HTML into raw Markdown source files under `sources/<source_id>/`.
+- Read web sources from stable or from an active session ref.
+- Validate optional wiki page `sources` frontmatter against returned web source IDs.
+- Commit wiki pages and web source files together on a session branch.
+- Fast-forward publish committed clean sessions as `publisher` or `admin`.
+
+Typical v2 MCP flow:
+
+```text
+wiki_session_start
+web_fetch
+source_read with ref = session_id
+wiki_session_patch with frontmatter.sources
+wiki_session_validate
+wiki_session_diff
+wiki_session_commit
+wiki_publish_session as publisher/admin
+source_read from stable
+```
+
+## v1 Scope
+
+v1 extends the v0 local git/worktree/session/validation/commit/MCP surface with document ingestion and stable publishing:
+
+- Upload source document blobs into workspace state outside git. Supported input MIME types are `application/pdf`, `text/markdown`, `text/x-markdown`, and `text/plain`.
+- Parse uploaded documents into session worktree files under `sources/<document_id>/`.
+- Configure external command parsers that read document bytes from stdin and emit Markdown on stdout.
+- Read source files from stable or from an active session ref.
+- Validate optional wiki page `sources` frontmatter against parsed source IDs.
+- Commit wiki pages and source files together on a session branch.
+- Fast-forward publish committed clean sessions as `publisher` or `admin`.
+
+Typical v1 MCP flow:
+
+```text
+wiki_session_start
+document_upload
+document_parse
+source_read with ref = session_id
+wiki_session_patch with frontmatter.sources
+wiki_session_validate
+wiki_session_diff
+wiki_session_commit
+wiki_publish_session as publisher/admin
+source_read from stable
+```
+
+## v0 Scope
+
+v0 is the historical baseline that v1 builds on. Supported in v0:
+
+- Initialize and inspect a local wiki workspace.
+- Start an MCP server over stdio.
+- Read stable wiki content.
+- Run read-only VFS commands against stable content.
+- Create isolated edit sessions.
+- Replace Markdown pages in a session.
+- Validate, diff, and commit session branches.
+- Enforce reader and writer tool permissions.
+
+Out of scope in v0:
+
+- Publish and rollback tools.
+- Search, document ingestion, web ingestion, and QA tools.
+- Remote git or pull request integration.
+- Web UI.
+
+## Quick Start
+
+Install Bun first; the published CLI runs TypeScript directly with the `bun` runtime:
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+Install the CLI:
+
+```bash
+bun add -g tgo-wiki
+```
+
+After installation, the `tgo-wiki` command is available on your PATH:
+
+```bash
+workspace="$HOME/.tgo-wiki/default"
+tgo-wiki init --workspace "$workspace"
+tgo-wiki status --workspace "$workspace"
+tgo-wiki mcp --workspace "$workspace" --role reader
+```
+
+`npm install -g tgo-wiki` also works when `bun` is already installed and available on PATH.
+
+For one-off usage without a global install:
+
+```bash
+bunx tgo-wiki status --workspace "$workspace"
+```
+
+## Source Checkout
+
+Install dependencies from a source checkout:
+
+```bash
+bun install --frozen-lockfile
+```
+
+Run the release-readiness gate:
+
+```bash
+bun run release:check
+```
+
+Run the executable MCP stdio example:
+
+```bash
+bun run example:mcp
+```
+
+The example creates a temporary workspace, starts the MCP server, lists tools, reads `wiki/index.md`, runs a writer session flow, commits the session branch, and cleans up the temporary workspace.
+
+Run the packaging smoke before handoff or release checks:
+
+```bash
+bun run smoke:pack
+```
+
+The packed smoke creates a tarball with `bun pm pack`, installs that tarball into a temporary consumer project, runs the installed `tgo-wiki` bin for `init` and `status`, starts MCP through the installed bin, and checks `initialize` plus `tools/list`.
+
+For a faster local check without packing, run:
+
+```bash
+bun run smoke:cli
+```
+
+## CLI
+
+Create a wiki workspace:
+
+```bash
+workspace="$(mktemp -d)"
+tgo-wiki init --workspace "$workspace"
+```
+
+Inspect workspace status:
+
+```bash
+tgo-wiki status --workspace "$workspace"
+```
+
+Start the MCP server as a reader:
+
+```bash
+tgo-wiki mcp --workspace "$workspace" --role reader
+```
+
+Start the MCP server as a writer:
+
+```bash
+tgo-wiki mcp --workspace "$workspace" --role writer
+```
+
+From a source checkout before publishing, replace `tgo-wiki` with `bun packages/server/src/cli.ts`.
+
+## MCP Tools
+
+Reader tools:
+
+- `vfs_exec`
+- `wiki_read`
+- `wiki_channel_status`
+- `source_list`
+- `source_read`
+
+Writer tools:
+
+- `wiki_session_start`
+- `wiki_session_patch`
+- `wiki_session_validate`
+- `wiki_session_diff`
+- `wiki_session_commit`
+- `document_upload`
+- `document_parse`
+
+Publisher and admin tools:
+
+- `web_fetch`
+- `wiki_publish_session`
+
+`web_fetch` rejects private, loopback, link-local, multicast, and reserved network targets by default. Workspace config can explicitly allow private hosts with `web.allowedPrivateHosts` when local or internal fixtures are intentional. `publisher` and `admin` roles can publish committed clean sessions. v0 did not expose publish or rollback behavior; see the v0 docs for that historical scope.
+
+## Documentation
+
+- [MCP usage guide](docs/mcp-usage.md)
+- [v2 acceptance gate](docs/v2-acceptance.md)
+- [v1 acceptance gate](docs/v1-acceptance.md)
+- [v0 acceptance gate](docs/v0-acceptance.md)
+- [v0 delivery checklist](docs/v0-delivery-checklist.md)
+- [Changelog](CHANGELOG.md)
+
+## Development
+
+Default unit and integration checks:
+
+```bash
+bun run check
+```
+
+Independent black-box tests:
+
+```bash
+bun run test:blackbox
+```
+
+Full v0 verification:
+
+```bash
+bun run verify:v0
+```
+
+Full v1 verification:
+
+```bash
+bun run verify:v1
+```
+
+Full v2 verification:
+
+```bash
+bun run verify:v2
+```
+
+Release-readiness check:
+
+```bash
+bun run release:check
+```
+
+Packaging smoke commands:
+
+```bash
+bun run smoke:pack
+bun run smoke:cli
+```
+
+GitHub Actions runs the default checks, black-box tests, and packed CLI smoke as separate jobs.