@telora/daemon 0.14.22 → 0.14.25

package/README.md

@@ -124,7 +124,64 @@ Instead of environment variables, you can use a JSON config file. The daemon loo
 2. Config file values
 3. Default values
 
-**Security note:** The `trackerId` must always be set via the `TELORA_TRACKER_ID` environment variable. It cannot be set in the config file (which is safe to commit to git).
+**Security note:** The `trackerId` may live in `~/.telora/daemon.json` (mode 0600, written by the connect flow) or in the `TELORA_TRACKER_ID` environment variable. Env vars take priority. The home-scoped daemon.json is the same posture as `~/.aws/credentials` -- not committable.
+
+### Workstation tracking install model
+
+Connect time, the daemon detects `telora-ai` (a Python CLI shipped under
+`scripts/`) on `PATH`. If present, connect:
+
+1. Pre-populates the user's local tracking DB with the redeem-derived
+   credentials (`telora-ai config tracker_id ...`, etc.) -- this skips
+   the registration-code round-trip that Settings > AI Trackers normally
+   requires
+2. Merges `PostToolUse` and `UserPromptSubmit` hook entries into
+   `~/.claude/settings.json` so a fresh Claude Code session is tracked
+   end-to-end without manual `telora-ai setup-hooks`
+
+If `telora-ai` is absent, connect prints a remediation hint and
+continues -- the daemon, MCP, and scaffolding parts of connect must
+succeed even when tracking can't be wired automatically.
+
+We picked detect-only (option c) over the alternatives:
+
+- **(a) pipx/uv install**: `telora-ai` is not on PyPI; no upstream
+  install target exists yet. A pipx install of a path-shipped script
+  doesn't generalise across machines that haven't checked out the repo.
+- **(b) Single-binary build / fold into daemon**: cleanest long-term but
+  out of scope here; it requires either a PyInstaller pipeline that
+  doesn't exist yet, or a TS rewrite of the tracking instrumentation.
+
+The remediation hint points users at the documented bring-up so they can
+opt into tracking manually when they want it.
+
+### `.mcp.json` resolution model (option C)
+
+The connect flow writes a credential-free `.mcp.json` so it can be committed and shared across collaborators:
+
+```json
+{
+  "mcpServers": {
+    "telora-products": {
+      "command": "npx",
+      "args": ["-p", "@telora/mcp-products@latest", "telora-mcp-products"]
+    }
+  }
+}
+```
+
+The MCP server resolves credentials at startup in this order:
+
+1. `TELORA_TRACKER_ID` + `TELORA_URL` env vars (explicit override)
+2. `~/.telora/daemon.json` (written by `telora-daemon connect`)
+
+We picked option (c) -- read from daemon.json -- over the alternatives:
+
+- **(a) Export from shell rc**: works only when the user's shell rc was sourced before `claude` was launched. Breaks under IDE-spawned Claude Code, `.envrc`-only setups, or any path where the rc didn't run.
+- **(b) Sourced `~/.telora/env`**: same brittleness as (a), plus a new file we'd have to teach the user about.
+- **(c) Read from `~/.telora/daemon.json`**: single source of truth, no shell-state coupling, same file the daemon already reads.
+
+The trade-off: the MCP server has to do one filesystem read per startup. That's negligible compared to npx's cold-cache cost on the same path.
 
 Available config file fields:
 - `teloraUrl` - Telora API URL

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commitSha": "166aa442",
-  "builtAt": "2026-04-27T16:10:47.411Z"
+  "commitSha": "fcf1d2e5",
+  "builtAt": "2026-04-29T12:17:15.904Z"
 }

package/dist/cli/connect.d.ts

@@ -1,10 +1,13 @@
 /**
  * `telora-daemon connect <token>` subcommand.
  *
- * Redeems a Telora connect token, writes the daemon config + .mcp.json,
- * installs @telora/daemon as a dev dep, and starts the daemon in the
- * background. Designed to be invoked at the tail end of the bash bootstrap
- * (`scripts/connect.sh`) so the user lands in `claude` with everything wired.
+ * Redeems a Telora connect token, writes the daemon config + a committable
+ * `.mcp.json`, then starts the daemon in the background via `npx -p
+ * @telora/daemon@latest telora-daemon run`. Designed to be invoked at the
+ * tail end of the bash bootstrap (`scripts/connect.sh`) so the user lands
+ * in `claude` with everything wired -- and importantly leaves no node-side
+ * footprint (no package.json, no node_modules, no dev dependency) in the
+ * user's repo. Rust/Python/Go/empty repos stay untouched.
  */
 /**
  * Production Telora API URL embedded in the published @telora/daemon package.
@@ -17,6 +20,8 @@ export interface RedeemResponse {
     organization_id?: string;
     product_id?: string;
     telora_url?: string;
+    /** True when redeem created the product on the fly (unbound flow). */
+    product_was_created?: boolean;
     error?: string;
     code?: string;
 }
@@ -33,11 +38,14 @@ export interface ConnectOptions {
     token: string;
     /** Override the Telora URL (default: TELORA_URL env or production). */
     teloraUrl?: string;
-    /** Repo path to install the daemon dep into (default: cwd). */
+    /** Repo path to wire the daemon into (default: cwd). */
     repoPath?: string;
     /** Skip starting the daemon (used by tests). */
     skipDaemonStart?: boolean;
-    /** Skip running `npm install` (used by tests). */
+    /**
+     * @deprecated The connect flow no longer runs `npm install`. This flag is
+     * retained as a no-op so existing callers / tests continue to compile.
+     */
     skipInstall?: boolean;
     /** Override IO (used by tests). */
     io?: Partial<ConnectIO>;
@@ -51,6 +59,11 @@ export interface ConnectResult {
     mcpConfigPath: string | null;
     starterPromptPath: string | null;
     daemonPid: number | null;
+    /** True when the redeem step bootstrapped the product (unbound flow). */
+    productWasCreated: boolean;
+    /** True when this connect found an existing product entry for repoPath in
+     *  daemon.json and short-circuited the proposed-name path. */
+    reusedExistingBinding: boolean;
 }
 /**
  * Map a redeem error code to a one-line remediation hint.
@@ -94,29 +107,103 @@ export declare function writeConnectDaemonConfig(params: {
  */
 export declare function writeStarterPromptArtifacts(repoPath: string, io: ConnectIO): string | null;
 /**
- * Append .telora/ and .mcp.json to .gitignore in the repo root if missing.
+ * Append `.telora/` to .gitignore in the repo root if missing.
+ *
+ * Earlier connect runs added `.mcp.json` here too, because the file embedded
+ * a per-user secret (TELORA_TRACKER_ID). The new `.mcp.json` shape is
+ * credential-free and meant to be committed; new runs no longer add it.
+ *
+ * If a previous run added `.mcp.json` to .gitignore, leave that line in
+ * place -- removing it would surface as a noisy migration. The user can
+ * delete the line on their own when they realize they want to commit the
+ * file.
  */
 export declare function ensureGitignoreEntries(repoPath: string, io: ConnectIO): void;
 /**
- * Ensure a package.json exists. If missing, write a minimal stub so we can
- * `npm install --save-dev` without npm complaining.
+ * Spawn the daemon as a detached background process via `npx`.
+ *
+ * Deliberately uses `npx -p @telora/daemon@latest telora-daemon run` (and
+ * NOT a node_modules path) so the connect flow does not require a
+ * `package.json` or `node_modules/` in the user's repo. This keeps the
+ * connect flow language-agnostic: a Rust/Python/Go/empty repo never gets
+ * a Node footprint.
+ *
+ * Bin name is explicit (`telora-daemon`) because the package's bins are
+ * `telora-daemon` and `telora-daemon-wrapper`; neither matches the unscoped
+ * package name `daemon`, so `npx @telora/daemon` cannot resolve a bin and
+ * aborts with a misleading error (lesson from commit 0368f4b6).
+ */
+export declare function startDaemonViaNpx(repoPath: string): number;
+/**
+ * Look up an existing product entry in `~/.telora/daemon.json` whose
+ * repoPath matches the given path. Returns the product id when found,
+ * else null. Used by runConnect for re-run idempotency: a second run on
+ * the same dir reuses the existing binding instead of creating a duplicate
+ * product on the unbound path.
+ */
+export declare function findExistingProductForRepo(repoPath: string): string | null;
+/**
+ * Write or merge a seeded `CLAUDE.md` at the repo root.
+ *
+ * - Fresh repo: writes the seeded block straight in.
+ * - Existing CLAUDE.md without the Telora delimiters: appends a delimited
+ *   Telora block at the end. The user's content is untouched.
+ * - Existing CLAUDE.md WITH the delimiters: replaces only the delimited
+ *   block. Re-runs are byte-identical (no churn, no duplication).
+ */
+export declare function writeOrMergeClaudeMd(repoPath: string, productName: string | null, io: ConnectIO): void;
+/**
+ * Write or deep-merge `<repo>/.claude/settings.json`.
+ *
+ * Fresh: writes the template directly.
+ * Existing: deep-merges our `permissions.allow` entries into the user's
+ * settings, deduplicating. All other top-level keys are untouched.
+ * Re-runs produce no diff.
  */
-export declare function ensurePackageJson(repoPath: string, io: ConnectIO): void;
+export declare function writeOrMergeClaudeSettings(repoPath: string, io: ConnectIO): void;
 /**
- * Install @telora/daemon as a dev dependency in the project.
- * Skipped if the package is already declared in devDependencies/dependencies.
+ * Locate the `telora-ai` Python CLI on PATH. Returns the absolute path if
+ * found, else null. Detection is the entire install model -- if the user
+ * doesn't have it, connect prints a remediation hint and continues
+ * (tracking is opt-in).
  */
-export declare function installDaemonIfNeeded(repoPath: string, io: ConnectIO): void;
+export declare function locateTeloraAi(): string | null;
 /**
- * Spawn the locally-installed daemon as a detached background process.
+ * Pre-populate the user's `~/.syntelyos/ai_tracking.db` config table with
+ * the redeem-derived credentials. Skips the
+ * `telora-ai register <code>` round-trip that Settings > AI Trackers
+ * normally requires -- the tracker row already exists in Telora (the
+ * redeem RPC inserted it), so all we need is to point the local DB at
+ * it.
+ *
+ * Each `telora-ai config <key> <value>` call is a single sqlite UPSERT;
+ * idempotent on re-runs.
  *
- * We deliberately do not reuse `startDaemonBackground` from daemon-process.ts
- * because that resolves the entry point relative to *this* file -- which,
- * during a fresh `npx --yes -p @telora/daemon telora-daemon connect ...` invocation, lives in
- * a transient npx cache. Spawning from the local install gives the daemon
- * a stable home for its lifetime.
+ * Returns true on success, false if any sub-call failed (the failure is
+ * surfaced via io.err but never aborts the connect flow).
+ */
+export declare function registerWorkstationLocally(params: {
+    teloraAiPath: string;
+    trackerId: string;
+    organizationId: string;
+    teloraUrl: string;
+    io: ConnectIO;
+}): boolean;
+/**
+ * Idempotent merge of `PostToolUse` and `UserPromptSubmit` hook entries
+ * into `~/.claude/settings.json`. Mirrors the shape of `telora-ai
+ * setup-hooks` in scripts/telora-ai but runs from the daemon connect flow
+ * so the user doesn't have to invoke it manually.
+ *
+ * Existing hook entries are preserved. Re-runs do not duplicate.
+ */
+export declare function mergeUserClaudeSettingsHooks(io: ConnectIO, homeOverride?: string): boolean;
+/**
+ * Write `.telora/.product-bootstrapped` -- a marker the starter prompt
+ * detects on first turn to offer a rename of the basename-derived product
+ * name. The starter prompt removes the marker after acting on it.
  */
-export declare function startInstalledDaemonBackground(repoPath: string): number;
+export declare function writeBootstrapMarker(repoPath: string, io: ConnectIO): void;
 /**
  * Run the connect flow.
  *

package/dist/cli/connect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/cli/connect.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/cli/connect.ts"],"names":[],"mappings":"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"}