tacticyl 0.1.4

package/README.md

@@ -0,0 +1,80 @@
+# tacticyl
+
+This is the companion for your Tacticyl business map and runs as a small program beside your code. It serves your map
+to Claude Code and Cursor, keeps your map current from each commit, and checks the folders your
+artifacts live in. It reads the repository in place, and only
+reports facts to your Tacticyl cloud workspace.
+
+## Install
+
+```
+npm i -g tacticyl
+tacticyl --version
+```
+
+One line on a machine with Node 22 or later (`node --version` prints the one it has).
+
+## Update
+
+```
+npm i -g tacticyl
+tacticyl --version
+```
+
+You can update the companion with the same command you used to install it, and `tacticyl --version`
+will print the installed version. When a newer version is available, a `tacticyl` command will
+print one line saying so and still run; if the installed version is older than the oldest one
+Tacticyl accepts, the command will not run until you update. Links, sign-in and hooks in your
+repositories stay as they are after you update. An agent session in Claude Code, Codex or Cursor
+that is already open will keep using the old version until you restart it.
+
+## What it does on your machine
+
+- **Installed.** Running `npm i -g tacticyl` will add a launcher, one bundled program file and a `tacticyl` command, and the tray icon helper is used only if you run `tacticyl tray`. The companion does not start at boot, run a background service, or update itself.
+- **When it runs.** The companion runs when you run a `tacticyl` command, when Claude Code, Codex or Cursor starts `tacticyl serve` for a session, and from hooks in a linked repository after each `git commit`, at the start of Claude Code or Cursor sessions, and after those agents edit files. Its status page is served at a 127.0.0.1 address that only this machine can reach.
+- **What it reads.** The companion reads the linked repository's manifests, lockfiles, migrations, compose and deploy files, environment variable names, `.tacticyl/inbox.md`, the opening of its README and architecture documents, and its commit and remote. In folders mounted with `tacticyl link --store`, it reads only the files the map names and the folders you chose to watch, to compute a hash of each.
+- **What it reports.** The companion reports facts to your Tacticyl cloud workspace at `https://app.tacticyl.com`. It reports facts about the repository: names, versions, counts, the remote and commit, environment variable names, the opening of the README and architecture documents, and the lines your agents append to `.tacticyl/inbox.md`. For each file in a store folder it reports the name, hash, size and time. It also reports the machine's name and what your agents send through Tacticyl's tools: a proposal, a document's path and summary, a finding's text, or an answer. Secrets are reported by name. When a command or a background run fails, the companion keeps a short note of the error on this machine, in `~/.tacticyl/errors.json`, and sends it to your workspace when you run `tacticyl report` and confirm it, or while error reports are on with `tacticyl report on`. A report contains the error and where in the companion it happened, and the companion, operating system and Node.js versions; file contents and environment variables are not included.
+- **What it writes.** In the repository, the companion writes `TACTICYL.md`, the `.tacticyl/` folder, and entries in `CLAUDE.md`, `AGENTS.md`, `.mcp.json`, `.cursor/`, `.claude/settings.json` and `.git/hooks/post-commit`. On this machine, it stores your sign-in in the keychain or `~/.tacticyl/credentials.json` and adds a tool entry to `~/.codex/config.toml`.
+- **Removing it.** Running `tacticyl remove` in the repository will remove what the companion set up there and sign this machine out, and `npm uninstall -g tacticyl` will remove the program. You can run `tacticyl remove --dry-run` to list the changes first.
+
+## Sign in
+
+```
+tacticyl login
+```
+
+Running `tacticyl login` will open a browser, where you approve this machine by name. The sign-in
+is stored in your operating system's keychain. Your Tacticyl cloud workspace also shows a one-line
+command, `tacticyl login --token <code>`, on the Overview, Agent and Account pages that pairs this
+machine. Running that line inside a repository will also link the repository, write the agent
+files and install the hooks.
+
+## In a repository
+
+```
+tacticyl link --business <id>     # once per repository; the id is in your workspace's URL
+tacticyl project                  # writes TACTICYL.md and gives your agents the tools
+tacticyl serve                    # serves tools to Claude Code, Codex and Cursor over stdio
+tacticyl audit                    # reads the code and keeps the map true
+tacticyl hooks install            # a commit runs the audit from now on
+tacticyl status                   # what it is doing, and the fix for anything wrong
+```
+
+Running `tacticyl link` will match an existing root by the repository's remote. A business your
+workspace drafted from this repository will be joined.
+
+`project` writes `TACTICYL.md` and, beside it, the files each agent reads: an import line in
+`CLAUDE.md` for Claude Code, `.cursor/rules/tacticyl.mdc` for Cursor, and a section in `AGENTS.md`
+for agents that follow that convention. It also gives Claude Code, Codex and Cursor Tacticyl's
+tools. If an agent's program is installed, `project` uses that agent's own command
+(`claude mcp add` or `codex mcp add`); otherwise it writes the agent's config file (`.mcp.json` for
+Claude Code, an entry in `~/.codex/config.toml` for Codex). Cursor has no such command and will
+always get `.cursor/mcp.json`. Codex's setting applies to every repository on this machine. You can
+skip an agent with `--no-claude-code`, `--no-codex` or `--no-cursor`.
+
+`tacticyl --help` lists the rest.
+
+## Help
+
+You can open Help in the top bar of your Tacticyl cloud workspace to walk through each step on a
+worked example. This machine appears on the Account page in your workspace once it has signed in.

package/bin/tacticyl.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// The `tacticyl` command. It runs `dist/cli.js` when that build is here, and otherwise the
+// single-file build in `dist/tacticyl.cjs`, which is all an install from npm carries.
+//
+// This file ships as written, so its comments are public: `scripts/package.mjs` says the rest.
+import { existsSync } from 'node:fs';
+
+const workspace = new URL('../dist/cli.js', import.meta.url);
+const bundle = new URL('../dist/tacticyl.cjs', import.meta.url);
+
+if (existsSync(workspace)) {
+  const { main } = await import(workspace.href);
+  await main(process.argv.slice(2));
+} else if (existsSync(bundle)) {
+  await import(bundle.href);
+} else {
+  console.error(
+    'tacticyl is not built here. In the workspace, `pnpm --filter tacticyl run build` writes ' +
+      'dist/; a published install carries dist/tacticyl.cjs.',
+  );
+  process.exitCode = 1;
+}