GUIDE

tcmts.cli.mcp.GUIDE · #r4mrivfg · term · runs anywhere

export const GUIDE: Record<string, string> = {
  model: `# The model

- A definition is a top-level function, const, class, type or interface. Its hash covers its code, with local names and formatting left out, and the hashes of what it uses. Comments and docs aren't part of it.
- Names are pointers: tcm_mv renames for free, and two names can point at one definition (tcm_cli ["alias", …]).
- A change to a definition gives it a new hash. Everything that uses it is re-hashed automatically (an update propagates), so there's never a stale build. What stops typechecking goes to tcm_todo rather than breaking silently.
- History is kept per command: tcm_cli ["history"], ["diff"], ["reset", "<n>"] undo anything. Each entry is named by what it changed, and by its message where the change was given one ("message" on the tools that change code, -m on the CLI; tcm_cli ["describe", "<n>", "-m", "…"] afterwards): say what and why. Branches: tcm_cli ["branch", "x"], ["switch", "x"], ["merge", "x"].
- Packages: imports of npm packages are pinned by compatible range and installed by tcm; nothing to npm install.`,
  editing: `# Editing

- tcm_edit ["lib.math.square", "lib.math.cube"] writes those definitions to a scratch file (scratch.ts unless you give one) with "// tcm: path …" lines saying where each goes back. Edit the file, then tcm_check, then tcm_update.
- A scratch file is ordinary TypeScript. It imports codebase definitions from "#codebase/<namespace path>" (import { square } from "#codebase/lib/math"), npm packages by name, Node builtins as "node:…".
- New definitions: put "// tcm: namespace lib.math" at the top of a scratch file and write them; tcm_update adds them there.
- Bare expressions in a scratch file (square(4)) are watch expressions: tcm_check evaluates and shows them, nothing saves them.
- Only top-level const (not let/var), function, class, type and interface; enums, namespaces and decorators aren't supported (use an as-const object).
- Definitions that refer to each other are a cycle, hashed and updated together. tcm_edit writes only the ones you name (and says what they're in a cycle with); saving saves the rest of the cycle with them, as it is.
- After tcm_update, check tcm_todo: dependents that no longer typecheck are listed there with the error.
- To undo: tcm_cli ["reset", "1"] brings back the names as they were before the last command.`,
  testing: `# Testing

- A test is a definition named test… (testSortIsStable) or any definition under a tests namespace. It passes by returning (or resolving) without throwing; expect and vi come from "vitest", node:assert works too.
- tcm_test [namespace] runs them with Vitest, in Node (or Chrome when a test renders a component with state). Passes are cached by hash: a re-run only runs tests whose code, or something they use, changed, and the ones that failed. fresh: true runs everything.
- Tests in a scratch file run when you tcm_check it.
- A package can declare suites: test definitions that run its command as a program (manifest suites: { cmd: ["e2e"] }, namespaces relative to the package's). tcm_test runs them too, each only if code it ran changed; definitions: true leaves them out, suites: true runs only them. To see one fail on the tcm from before a fix: bin: {"tcm": "<that tcm.js>"} (tcm_status names the one this server runs).`,
  apps: `# Apps

- An app is a definition (a React component, or a handler); tcm_cli ["dev", "<name>"] serves it while you work, ["build", …] and ["start", …] for production.
- Where code runs (server or browser) is inferred from what it uses: no "use client"/"use server". A browser function calling a server one becomes a call by hash. tcm_view shows where each definition runs.
- The server library has the server API: requests, sessions, typed tables (table<Row>("name")), background jobs (enqueue, every); tcm_cli ["lib", "add", "tcm", "server"] mounts it at <root>.lib.server (tcm's own code: #codebase/tcmts/server).`,
  packages: `# Packages and releases

- A definition named manifest makes its namespace a package: { name, exports, bin, with, files }.
- tcm_cli ["release", "check", "<pkg>"] shows the next version, from semver checks on the package's API since its last release; ["release", "<pkg>"] makes it (["release", "<pkg>", "--draft"] first, to write a summary).
- tcm_cli ["pack", "<pkg>@<version>"] makes the npm package; publishing is done by hand.`,
  mirrors: `# Mirrors

- A codebase can mirror a directory of source files (tcm_cli ["import", "<dir>", "--into", "<ns>", "--mirror"]): changes made in tcm are written back to those files as edits, so git and other editors see them. A new namespace gets a file; a rename reaches files near the mirror that use the name (scripts, tests). tcm_status says whether there's one.
- With a mirror you can also edit its files directly (or git can: a pull, a checkout): the next tool call imports what changed first, definitions removed from the files included. A file that doesn't import yet (an edit half made) isn't written to until it does.
- Releases of a mirrored codebase are recorded with its files (tcm-releases.json) and need the files committed first.`,
  troubleshooting: `# When something goes wrong

- "not in the codebase" from an import in a scratch file: the name is wrong, tcm_find it.
- A conflicted name (after a merge: tcm_todo labels its definitions ours and theirs): tcm_edit it for its sides merged from the base in a file named after it (lib.k.ts), with conflict markers where both changed the same lines, and what each side changed; take them out and tcm_update that file resolves it (history says "resolve lib.k (merged)"). One that uses another conflicted name can't typecheck until that's settled: tcm_edit both, into one file. tcm_resolve with side "ours" or "theirs" keeps one whole; tcm_cli ["diff", "<name>"] shows the base against each side, ["diff", "#a", "#b"] any two definitions.
- A test passes from cache but you changed something outside the codebase (a file, the network): tcm_test with fresh: true.
- tcm_cli ["verify"] re-renders and re-hashes everything; it must report the identity.
- tcm_cli ["help"] lists every command; tcm_cli ["<command>", "--help"] explains one.`,
}

used by

• tcmts.cli.mcp.TOOLS