@trce/cli 0.1.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+Notable changes to trce are documented here.
+
+## 0.1.0-beta.1 — Unreleased
+
+First public beta.
+
+### Added
+
+- Self-contained native CLI packages for macOS, Linux, and Windows on arm64
+  and x64.
+- Claude Code and Codex CLI hook installation, local recording, normalization,
+  on-device redaction, one-shot sharing, live sharing, and unshare.
+- Local device identity with owner-only POSIX permissions.
+- Retry-safe bounded uploads and visible oversized-event truncation metadata.
+- `@trce/protocol` with runtime Zod schemas and TypeScript declarations.
+- Cross-platform package smoke tests, fixture goldens, schema validation, and
+  planted-secret coverage.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tair Asim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# trce
+
+![trce — See what your coding agents do](docs/github-social-preview.png)
+
+See what your coding agents do.
+
+[![CI](https://github.com/assimovt/trce-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/assimovt/trce-cli/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-magenta.svg)](LICENSE)
+
+`trce` records Claude Code and Codex CLI sessions locally as structured events.
+Inspect each trace on your machine, or explicitly share it for live viewing and
+replay.
+
+> Recording is local. Nothing leaves your machine until you explicitly share.
+> Redaction runs on-device before every upload.
+
+## Install
+
+```sh
+npm install -g @trce/cli@next
+trce help
+```
+
+The package installs a self-contained native executable; Bun is not required at
+runtime. Install scripts and optional dependencies must be enabled so npm can
+select the binary for your platform.
+
+Supported targets:
+
+- macOS, Linux, and Windows
+- arm64 and x64
+
+## Quick start
+
+Preview and install hooks for the current project:
+
+```sh
+# Claude Code
+trce init --harness claude-code --scope project --dry-run
+trce init --harness claude-code --scope project --yes
+
+# Codex CLI
+trce init --harness codex-cli --scope project --dry-run
+trce init --harness codex-cli --scope project --yes
+```
+
+Use `--scope global` to install for every project. Start a new Claude Code or
+Codex session after installation; hooks then record lifecycle events locally in
+`~/.trce/spool/`.
+
+Share the latest session when you choose:
+
+```sh
+trce share --latest          # one-shot share
+trce share --latest --live   # live updates until the session ends
+trce share --latest --local  # redacted JSON and HTML; no upload
+```
+
+Claude Code users can also run `/trce-share` or `/trce-share live`. In Codex,
+ask the agent to run the same `trce share` command, or run it yourself.
+
+Delete a hosted copy without deleting the local recording:
+
+```sh
+trce unshare https://trce.sh/t/<share-id>
+```
+
+## How it works
+
+1. Harness hooks append native events to a local JSONL spool. `trce spool` does
+   no network work, normalization, or redaction.
+2. An explicit share action combines the spool with the native transcript,
+   normalizes it, and redacts it on-device.
+3. The CLI writes a local `trace.json`, redaction report, and HTML preview. It
+   uploads only when `--local` is not set.
+
+Long sessions are uploaded in ordered, retry-safe batches. Oversized event
+payloads are reduced to a visible first/last preview for sharing while the raw
+local recording remains untouched.
+
+## Privacy
+
+Applied `trce init` creates a random device token in `~/.trce/config.toml`.
+The token is never printed or included in trace data; it is used only as the
+authorization header for explicit publish and unshare actions. Existing tokens
+are preserved. On macOS and Linux, the directory is mode `0700` and the config
+file is mode `0600`.
+
+Redaction masks secret-looking keys and values, common credential formats,
+authorization headers, database URLs, PEM keys, values loaded from local
+`.env*` files, and configured extra values. Redaction is best-effort, and every
+share includes a visible report. Review sensitive traces before sharing.
+
+## Documentation
+
+- [CLI interface](docs/cli-interface.md)
+- [Publish protocol](docs/publish-protocol.md)
+- [Trace schema](docs/trace-schema.md) and [JSON Schema](docs/trace-schema.json)
+- [Project scope and privacy invariants](docs/project-scope.md)
+- [`@trce/protocol`](packages/protocol/README.md)
+
+The Zod definitions in `packages/schema` are the source of truth for the
+`trce: "0.1"` format. Unknown native records degrade to `other` rather than
+crashing when harness formats drift.
+
+## Development
+
+Requires Bun 1.3.12. Node.js 24 and npm 11 are also used by package smoke tests.
+
+```sh
+bun install --frozen-lockfile
+bun run verify
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for fixture, privacy, and pull-request
+requirements.
+
+## Community
+
+- Use [GitHub Issues](https://github.com/assimovt/trce-cli/issues) for sanitized
+  bug reports and focused feature proposals.
+- Use [SECURITY.md](SECURITY.md) for private vulnerability reports. Never post
+  raw traces, credentials, or device tokens publicly.
+- Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+Maintained by Tair Asim. Released under the [MIT License](LICENSE).

package/bin/trce.exe

@@ -0,0 +1,5 @@
+echo "Error: trce's postinstall script was not run." >&2
+echo "" >&2
+echo "Reinstall @trce/cli without --ignore-scripts or --omit=optional." >&2
+echo "The install needs its platform-specific native binary package." >&2
+exit 1

package/install.cjs

@@ -0,0 +1,88 @@
+"use strict";
+
+const { chmodSync, copyFileSync, existsSync, renameSync } = require("node:fs");
+const { dirname, join } = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const PLATFORM_PACKAGES = {
+  "darwin-arm64": {
+    binary: "bin/trce",
+    packageName: "@trce/cli-darwin-arm64",
+  },
+  "darwin-x64": {
+    binary: "bin/trce",
+    packageName: "@trce/cli-darwin-x64",
+  },
+  "linux-arm64": {
+    binary: "bin/trce",
+    packageName: "@trce/cli-linux-arm64",
+  },
+  "linux-x64": {
+    binary: "bin/trce",
+    packageName: "@trce/cli-linux-x64",
+  },
+  "win32-arm64": {
+    binary: "bin/trce.exe",
+    packageName: "@trce/cli-win32-arm64",
+  },
+  "win32-x64": {
+    binary: "bin/trce.exe",
+    packageName: "@trce/cli-win32-x64",
+  },
+};
+
+function platformPackage(platform = process.platform, arch = process.arch) {
+  return PLATFORM_PACKAGES[`${platform}-${arch}`] ?? null;
+}
+
+function install() {
+  // The source checkout builds platform packages explicitly. Published npm
+  // tarballs do not contain .git and must always install their native binary.
+  if (existsSync(join(__dirname, ".git"))) {
+    return;
+  }
+
+  const target = platformPackage();
+  if (target === null) {
+    throw new Error(`Unsupported platform: ${process.platform} ${process.arch}`);
+  }
+
+  const packageJson = require.resolve(`${target.packageName}/package.json`);
+  const packageVersion = require(packageJson).version;
+  const rootVersion = require(join(__dirname, "package.json")).version;
+  if (packageVersion !== rootVersion) {
+    throw new Error(
+      `Native package version mismatch: @trce/cli ${rootVersion}, ${target.packageName} ${packageVersion}`,
+    );
+  }
+
+  const source = join(dirname(packageJson), target.binary);
+  const destination = join(__dirname, "bin", "trce.exe");
+  if (!existsSync(source)) {
+    throw new Error(`Native trce binary is missing from ${target.packageName}`);
+  }
+
+  const smoke = spawnSync(source, ["help"], { encoding: "utf8" });
+  if (smoke.status !== 0) {
+    throw new Error(smoke.stderr || smoke.stdout || `Could not run ${source}`);
+  }
+
+  try {
+    renameSync(source, destination);
+  } catch {
+    copyFileSync(source, destination);
+  }
+  chmodSync(destination, 0o755);
+}
+
+module.exports = { install, platformPackage };
+
+if (require.main === module) {
+  try {
+    install();
+  } catch (error) {
+    console.error(`trce install failed: ${error instanceof Error ? error.message : String(error)}`);
+    console.error("Reinstall without --ignore-scripts or --omit=optional.");
+    process.exit(1);
+  }
+}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@trce/cli",
+  "version": "0.1.0-beta.1",
+  "description": "Local recorder and share CLI for coding-agent traces.",
+  "author": "Tair Asim",
+  "homepage": "https://trce.sh",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/assimovt/trce-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/assimovt/trce-cli/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "bun@1.3.12",
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "arm64",
+    "x64"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "agents",
+    "claude-code",
+    "codex",
+    "tracing"
+  ],
+  "bin": {
+    "trce": "./bin/trce.exe"
+  },
+  "files": [
+    "bin/trce.exe",
+    "install.cjs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "docs/github-social-preview.png"
+  ],
+  "workspaces": [
+    "packages/*",
+    "apps/*"
+  ],
+  "optionalDependencies": {
+    "@trce/cli-darwin-arm64": "0.1.0-beta.1",
+    "@trce/cli-darwin-x64": "0.1.0-beta.1",
+    "@trce/cli-linux-arm64": "0.1.0-beta.1",
+    "@trce/cli-linux-x64": "0.1.0-beta.1",
+    "@trce/cli-win32-arm64": "0.1.0-beta.1",
+    "@trce/cli-win32-x64": "0.1.0-beta.1"
+  },
+  "scripts": {
+    "build": "bun run scripts/build-bundle.ts",
+    "build:binary": "bun run scripts/build-platform.ts --target current",
+    "build:binaries": "bun run scripts/build-platform.ts --target all",
+    "build:cli": "bun run build",
+    "build:protocol": "bun run scripts/build-protocol.ts",
+    "check:packages": "bun run scripts/check-packages.ts",
+    "dev:cli": "bun run packages/cli/src/index.ts",
+    "lint": "biome lint .",
+    "pack:check": "npm_config_cache=./dist/.npm-cache npm pack --dry-run",
+    "pack:local": "bun run scripts/pack-local.ts --target current",
+    "pack:protocol": "bun run scripts/pack-protocol.ts",
+    "pack:protocol:check": "npm_config_cache=./dist/.npm-cache npm pack ./packages/protocol --dry-run",
+    "postinstall": "node install.cjs",
+    "prepack": "bun run check:packages",
+    "schema:check": "bun run scripts/generate-json-schema.ts --check",
+    "schema:generate": "bun run scripts/generate-json-schema.ts",
+    "release:check": "bun run scripts/check-release.ts --version 0.1.0-beta.1 --tag next",
+    "smoke:package": "bun run scripts/smoke-package.ts --target current",
+    "smoke:protocol": "bun run scripts/smoke-protocol.ts",
+    "test": "bun test",
+    "typecheck": "bun run build:protocol && tsc -p packages/schema/tsconfig.json --noEmit && tsc -p packages/protocol/tsconfig.json --noEmit && tsc -p packages/cli/tsconfig.json --noEmit && tsc -p scripts/tsconfig.json --noEmit",
+    "verify": "bun run lint && bun run typecheck && bun run test && bun run check:packages && bun run schema:check && bun run build"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.2",
+    "@types/bun": "^1.3.14",
+    "typescript": "^7.0.2"
+  }
+}