@reticlehq/server 3.6.0 → 3.7.0

package/dist/command/cli/project-name.js

@@ -11,6 +11,12 @@
  * A repo already knows its name: the directory it lives in. That is not a guess, it is the name its
  * owner chose and the one they will look for in a project list.
  */
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { relative } from 'node:path';
+import { z } from 'zod';
+import { PROJECT_ID_HASH_LENGTH } from '@reticlehq/core';
+import { CredentialRefusedError, api, hint } from './cloud-kit.js';
 /** Cap the slug so a deep or oddly-named checkout cannot produce an unreadable project id. */
 const MAX_SLUG = 48;
 /** The id used when a directory name yields nothing usable — the historical behaviour, unchanged. */
@@ -37,8 +43,107 @@ export const slugifyProjectName = (raw) => {
  * do to rotate a key or repoint an environment — must land in that same project or the history
  * silently splits in two, which is worse than the shared-bucket problem this fixes.
  */
-export const defaultProjectFor = (cwdBasename, existingProjectId) => {
+export const defaultProjectFor = (cwdBasename, existingProjectId, 
+/** The `projectId` `init` wrote into `.reticle.json`, when there is one. */
+localProjectId) => {
     if (existingProjectId !== undefined && existingProjectId.length > 0)
         return existingProjectId;
-    return slugifyProjectName(cwdBasename);
+    // The name part of `init`'s `<name>-<hash>`, else the id as written: a name the owner chose.
+    const named = localProjectId === undefined || 0 === localProjectId.length
+        ? undefined
+        : (nameOfLocalId(localProjectId) ?? localProjectId);
+    return slugifyProjectName(named ?? cwdBasename);
 };
+/** `init`'s id is the app's name and a short hash of where it lives: `nina-todo-f96721e8`. */
+const LOCAL_ID = new RegExp(`^(.+)-[0-9a-f]{${String(PROJECT_ID_HASH_LENGTH)}}$`);
+/**
+ * The name part of the id `init` wrote. One project carried two names: `.reticle.json` said
+ * `nina-todo-f96721e8` (from the package) while the dashboard said `app` (the folder), so the person
+ * looked for one and the list showed the other. The dashboard now takes the name `init` wrote.
+ */
+function nameOfLocalId(localProjectId) {
+    return LOCAL_ID.exec(localProjectId)?.[1];
+}
+export const CreatedProjectSchema = z.object({ projectId: z.string(), name: z.string() });
+const ProjectsListSchema = z.object({
+    projects: z.array(z.object({ projectId: z.string(), name: z.string(), repo: z.string().optional() })),
+});
+/** ` in workspace "<name>"`, or nothing when no name is known. */
+export const inWorkspace = (name) => name === undefined || 0 === name.length ? '' : ` in workspace "${name}"`;
+/** Characters of the repository identity: enough to tell repositories apart, nothing to read. */
+const REPO_ID_CHARS = 16;
+/**
+ * Which repository, and which folder in it, a project folder is: a hash of the `origin` remote and
+ * the folder's path inside the checkout, so every clone of one app agrees and two different apps
+ * both named `web` do not. Undefined outside git or with no remote. Neither leaves the machine.
+ */
+export function repoIdentity(dir) {
+    try {
+        const git = (...args) => execFileSync('git', args, {
+            cwd: dir,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        const remote = git('config', '--get', 'remote.origin.url')
+            .replace(/\.git$/, '')
+            .replace(/^[a-z+]+:\/\/|^[^@]+@/i, '')
+            .replace(':', '/')
+            .toLowerCase();
+        if (0 === remote.length)
+            return undefined;
+        const inside = relative(git('rev-parse', '--show-toplevel'), dir).split('\\').join('/');
+        return createHash('sha256')
+            .update(`${remote}\u0000${inside}`)
+            .digest('hex')
+            .slice(0, REPO_ID_CHARS);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The id for the project the caller named, creating it if it does not exist yet — and saying so,
+ * in which workspace. A project of that NAME made for another repository is not reused: two apps
+ * whose package is `web` shared one dashboard project. A project with no recorded repository, or an
+ * id named outright, is reused as before.
+ */
+/** Projects named when creating one was refused. */
+const MAX_NAMED = 5;
+export async function resolveProjectId(url, token, wanted, workspace, repo, 
+/**
+ * The id `init` wrote into `.reticle.json`, for a project created by default: the platform is
+ * asked to keep it, so the folder and the dashboard name one project by one id. A platform that
+ * does not know the field ignores it and answers with its own, which is what gets linked.
+ */
+localId) {
+    const { projects } = ProjectsListSchema.parse(await api('GET', `${url}/v1/projects`, token));
+    const lc = wanted.toLowerCase();
+    const holding = localId === undefined ? undefined : projects.find((p) => p.projectId === localId);
+    if (holding !== undefined)
+        return holding.projectId;
+    const match = projects.find((p) => p.projectId === wanted ||
+        (p.name.toLowerCase() === lc &&
+            (repo === undefined || p.repo === undefined || p.repo === repo)));
+    if (match !== undefined)
+        return match.projectId;
+    let answer;
+    try {
+        answer = await api('POST', `${url}/v1/projects`, token, {
+            name: wanted,
+            ...(repo === undefined ? {} : { repo }),
+            ...(localId === undefined ? {} : { projectId: localId }),
+        });
+    }
+    catch (error) {
+        // Refused to create one (a contributor): the platform's words, then the step that works.
+        if (error instanceof CredentialRefusedError ||
+            !(error instanceof Error) ||
+            0 === projects.length)
+            throw error;
+        const names = projects.map((p) => p.name).slice(0, MAX_NAMED);
+        throw new Error(`${error.message}\nTo link one that exists: ${names.map((n) => `\`reticle connect --project ${n}\``).join(', ')}`);
+    }
+    const created = CreatedProjectSchema.parse(answer);
+    hint(`created project "${wanted}" (${created.projectId})${inWorkspace(workspace)} — it did not exist yet`);
+    return created.projectId;
+}

package/dist/command/cli/setup-mcp-cli.d.ts

@@ -14,7 +14,23 @@ import type { OnboardingStep } from '@reticlehq/core/telemetry';
  * so the entry point supplies it and every layer below stays a function of its arguments.
  */
 export type StepReporter = (step: OnboardingStep) => void;
-export declare function handleSetupMcp(reportStep: StepReporter, standalone?: boolean): void;
+/** How many coding agents on this machine have Reticle's tools after this run. */
+export declare function handleSetupMcp(reportStep: StepReporter, standalone?: boolean): number;
+/**
+ * The one line the launchers read and strip: what they cannot know and the next steps depend on.
+ *
+ * The launchers own the closing words (served from main, so wording changes on merge) and used to
+ * print "restart your coding agent" to a machine with none, and "cd your-app" to somebody already
+ * standing in it. An older launcher shows this line as is; a launcher reading an older CLI finds no
+ * line and keeps its generic wording, so neither half has to ship first.
+ */
+export declare const INSTALL_RESULT_PREFIX = "RETICLE_INSTALL";
+/** Whether the folder the installer ran in is an app: `init` runs here, or after a `cd`. */
+export declare const InstallAppHere: {
+    readonly HERE: "here";
+    readonly NONE: "none";
+};
+export declare function installResultLine(agents: number, cwd: string): string;
 /**
  * `reticle setup install` — the Node half of the one-line installer.
  *

package/dist/command/cli/setup-mcp-cli.js

@@ -1,11 +1,12 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { claudeAddCommand, McpClient, probeCli, terminalWidth, wrapForTerminal, } from '@reticlehq/init';
-import { installClosing, tutorialShownSteps } from './tutorial.js';
+import { tutorialShownSteps } from './tutorial.js';
 import { setupMcp, knownClientLabels } from '../setup/setup-mcp.js';
 import { reportInstallSteps } from '../setup/setup-install.js';
 import { registerOtherAgents } from '../setup/setup-command.js';
+/** How many coding agents on this machine have Reticle's tools after this run. */
 export function handleSetupMcp(reportStep, standalone = true) {
     const io = {
         exists: (p) => existsSync(p),
@@ -45,7 +46,7 @@ export function handleSetupMcp(reportStep, standalone = true) {
         io.print(0 < preRegistered
             ? `None of ${knownClientLabels().join(', ')} is installed here yet. The agents above are pre-registered and have Reticle's tools once installed; install one of the others, then run \`reticle setup mcp\` again.`
             : `No coding agent config found. Looked for: ${knownClientLabels().join(', ')}. Install one, then run \`reticle setup mcp\` again.`);
-        return;
+        return 0;
     }
     for (const id of result.registered)
         io.print(`  ✓ ${id}`);
@@ -92,6 +93,25 @@ export function handleSetupMcp(reportStep, standalone = true) {
         io.print('Restart your agent for it to pick up the new server.');
         io.print('Then: cd <your project> && reticle init');
     }
+    return result.registered.length + result.alreadyThere.length;
+}
+/**
+ * The one line the launchers read and strip: what they cannot know and the next steps depend on.
+ *
+ * The launchers own the closing words (served from main, so wording changes on merge) and used to
+ * print "restart your coding agent" to a machine with none, and "cd your-app" to somebody already
+ * standing in it. An older launcher shows this line as is; a launcher reading an older CLI finds no
+ * line and keeps its generic wording, so neither half has to ship first.
+ */
+export const INSTALL_RESULT_PREFIX = 'RETICLE_INSTALL';
+const APP_MARKERS = ['package.json', 'index.html'];
+/** Whether the folder the installer ran in is an app: `init` runs here, or after a `cd`. */
+export const InstallAppHere = { HERE: 'here', NONE: 'none' };
+export function installResultLine(agents, cwd) {
+    const app = APP_MARKERS.some((file) => existsSync(join(cwd, file)))
+        ? InstallAppHere.HERE
+        : InstallAppHere.NONE;
+    return `${INSTALL_RESULT_PREFIX} agents=${String(agents)} app=${app}`;
 }
 /**
  * `reticle setup install` — the Node half of the one-line installer.
@@ -102,16 +122,17 @@ export function handleSetupMcp(reportStep, standalone = true) {
  */
 export function handleSetupInstall(opts, reportStep) {
     reportInstallSteps({ runtimeSecs: opts.runtimeSecs, installSecs: opts.installSecs }, reportStep);
+    let agents = 0;
     if (opts.mcp) {
-        handleSetupMcp(reportStep, false);
+        agents = handleSetupMcp(reportStep, false);
     }
     else {
         process.stdout.write('Skipping MCP registration (--no-mcp).\n');
     }
-    // Installation and onboarding are one script, so the tour prints here and is not gated on
-    // anything — see installClosing for the heuristic this replaced and why it reached nobody.
-    process.stdout.write(`${wrapForTerminal(installClosing(opts.mcp), terminalWidth())}\n`);
-    // Shown, so the ONBOARD steps are a fact rather than a guess.
+    // No closing here: the installer prints the next step and the agent prompt itself, right after
+    // this returns, so what this prints is progress and nothing else. Those two blocks are what the
+    // ONBOARD steps below now stand for: what Reticle is for, shown before anything is asked of anyone.
     for (const step of tutorialShownSteps())
         reportStep(step);
+    process.stdout.write(`${installResultLine(agents, process.cwd())}\n`);
 }

package/dist/command/cli/status/status-lines.d.ts

@@ -19,6 +19,7 @@ export declare const StatusLabel: {
     readonly DAEMON: "daemon";
     readonly SESSIONS: "sessions";
     readonly AGENT_LINK: "agent link";
+    readonly ACCOUNT: "account";
     readonly NEXT: "next";
     readonly SPLIT_BRAIN: "split brain";
     readonly UPDATE: "update";

package/dist/command/cli/status/status-lines.js

@@ -19,6 +19,7 @@ export const StatusLabel = {
     DAEMON: 'daemon',
     SESSIONS: 'sessions',
     AGENT_LINK: 'agent link',
+    ACCOUNT: 'account',
     NEXT: 'next',
     SPLIT_BRAIN: 'split brain',
     UPDATE: 'update',
@@ -101,9 +102,40 @@ export function statusLines(fields) {
         if (why !== undefined)
             lines.push(continuation(why));
     }
+    // Who is signed in, and whether this repo is linked: what `whoami` used to answer. Only when the
+    // caller looked, which is what the key being present means.
+    if ('signedInAs' in fields) {
+        const who = str(fields, 'signedInAs');
+        const project = str(fields, 'linkedProject');
+        // Signed in to one workspace, a repo can still send to another: say which it sends to.
+        const workspace = str(fields, 'linkedWorkspace');
+        // A key the platform refused at the last sync is the answer, not "not signed in": a member
+        // removed from the workspace was told to connect while the key was set, and refused.
+        const refused = str(fields, 'keyRefused');
+        lines.push(row(StatusLabel.ACCOUNT, refused !== undefined
+            ? `${NOT_OK} refused at the last sync: ${refused}`
+            : who === undefined
+                ? `${NOT_OK} not signed in`
+                : `${OK} signed in as ${who}`));
+        const apps = appLinks(fields['workspaceApps']);
+        if (project === undefined && 0 < apps.length)
+            for (const { app, project: linked } of apps)
+                lines.push(continuation(null === linked
+                    ? `${app} is not linked: run \`reticle connect\` in ${app}`
+                    : `${app} is linked to ${linked}`));
+        else
+            lines.push(continuation(project === undefined
+                ? 'this repo is not linked: run `reticle connect`'
+                : `this repo is linked to ${project}${workspace === undefined ? '' : ` in workspace "${workspace}"`}`));
+    }
     const client = str(fields, 'mcpClient');
-    if (client !== undefined)
-        lines.push(row(StatusLabel.AGENT_LINK, client));
+    if (client !== undefined) {
+        // The state in words (`mcpClientSaid`), never the record's own name for it.
+        lines.push(row(StatusLabel.AGENT_LINK, str(fields, 'mcpClientSaid') ?? client));
+        const action = str(fields, 'mcpClientAction');
+        if (action !== undefined)
+            lines.push(continuation(action));
+    }
     for (const [label, key] of [
         [StatusLabel.NEXT, 'nextAction'],
         [StatusLabel.SPLIT_BRAIN, 'splitBrain'],
@@ -115,3 +147,16 @@ export function statusLines(fields) {
     }
     return lines;
 }
+/** A workspace root's apps and their links, read defensively off the status fields. */
+function appLinks(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((raw) => {
+        if ('object' !== typeof raw || null === raw)
+            return [];
+        const { app, project } = raw;
+        return 'string' === typeof app
+            ? [{ app, project: 'string' === typeof project ? project : null }]
+            : [];
+    });
+}

package/dist/command/cli/status/workspace-links.d.ts

@@ -0,0 +1,10 @@
+export interface AppLink {
+    /** The app's directory, relative to the root. */
+    app: string;
+    /** The project it sends to, or null when it is not linked. */
+    project: string | null;
+}
+/** Each app under `root`, in name order, with its link. Empty when `root` is no workspace. */
+export declare function workspaceAppLinks(root: string, linkOf: (appDir: string) => Promise<string | null>): Promise<AppLink[]>;
+/** The project an app folder's link file names, or null with none: local only, as status is. */
+export declare function localLinkOf(appDir: string): Promise<string | null>;

package/dist/command/cli/status/workspace-links.js

@@ -0,0 +1,29 @@
+/**
+ * The apps of a workspace root and the project each is linked to, for `reticle status` run at a root
+ * that is no app of its own: "this repo is not linked" there named nothing that could be acted on.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ReticleDir, asRecord, asString } from '@reticlehq/core';
+import { SILENT_HOST, buildNodeIo, findWorkspaceApps } from '@reticlehq/init';
+/** Each app under `root`, in name order, with its link. Empty when `root` is no workspace. */
+export async function workspaceAppLinks(root, linkOf) {
+    let apps;
+    try {
+        apps = findWorkspaceApps(buildNodeIo(root, SILENT_HOST));
+    }
+    catch {
+        return [];
+    }
+    return Promise.all([...apps].sort().map(async (app) => ({ app, project: await linkOf(join(root, app)) })));
+}
+/** The project an app folder's link file names, or null with none: local only, as status is. */
+export function localLinkOf(appDir) {
+    try {
+        const link = JSON.parse(readFileSync(join(appDir, ReticleDir.ROOT, ReticleDir.CLOUD_LINK_FILE), 'utf8'));
+        return Promise.resolve(asString(asRecord(link)['projectId']) ?? null);
+    }
+    catch {
+        return Promise.resolve(null);
+    }
+}

package/dist/command/cli/try-command.d.ts

@@ -0,0 +1,96 @@
+import type { CloudConfig } from '../../memory/cloud/cloud-sync.js';
+import { type FreeDrive } from '../../features/harness/platform/platform-drives.js';
+export declare const MSG_SIGN_IN_FIRST = "Sign in first: reticle connect (it is free, no card)";
+/** The whole drive, model turns and browser included, before the CLI stops waiting for it. */
+export declare const TRY_BUDGET_MS = 120000;
+/** Model turns in the one free drive. Bounds what it costs, not what it may find. */
+export declare const TRY_MAX_STEPS = 40;
+export interface TryJourney {
+    title: string;
+    status: string;
+}
+/** What one drive came back with, or the sentence that says why it could not run. */
+export interface TryDrive {
+    journeys: TryJourney[];
+    runIds: string[];
+    error?: string;
+}
+export interface TryPorts {
+    /** The credential `reticle connect` filed for this folder, or null when it is not linked. */
+    linked: () => Promise<CloudConfig | null>;
+    requestDrive: (cloud: CloudConfig) => Promise<FreeDrive>;
+    drive: (request: {
+        url: string;
+        driveId: string;
+        persona?: string;
+    }) => Promise<TryDrive>;
+    /** Send the drive's run, as `reticle push` does. True when the cycle succeeded. */
+    sync: (runIds: readonly string[]) => Promise<boolean>;
+    dashboardUrl: (cloud: CloudConfig) => Promise<string | undefined>;
+    out: (line: string) => void;
+    fail: (line: string) => void;
+}
+export interface TryArgs {
+    url: string;
+    persona?: string;
+}
+/** `try <url> [--persona <who>]`, or the sentence that says what is missing. */
+export declare function parseTryArgs(argv: readonly string[]): TryArgs | {
+    error: string;
+};
+/** The summary, worst news last so it is the line a reader's eye lands on. Pure. */
+export declare function summarizeTry(journeys: readonly TryJourney[]): string[];
+export declare function runTry(args: TryArgs, ports: TryPorts): Promise<number>;
+/** The journeys out of an explore report, or one journey graded from the drive when unplanned. */
+export declare function journeysOf(report: Record<string, unknown>, persona?: string): TryJourney[];
+/** What `try` borrows from the cloud commands, passed in so neither module imports the other. */
+export interface TryCloud {
+    push: () => Promise<number>;
+    dashboardUrl: (cloud: CloudConfig) => Promise<string | undefined>;
+}
+/** `reticle try`, wired to this machine. Returns the exit code. */
+export declare function cmdTry(argv: readonly string[], cloudCommands: TryCloud): Promise<number>;
+/**
+ * How `init` ends once the connection is proved: what Reticle sees of the app, what it is missing,
+ * and the prompt that hands the rest to the coding agent, which proves the first flow. `init` never
+ * drives: the Harness is opt-in and unlocks at a coverage score (core's `instrumentation-coverage.ts`), and a
+ * freshly wired app is rarely there yet.
+ *
+ * Read from the daemon's `/status`, the same coverage `doctor` prints, so the two never disagree.
+ */
+/** What a project that is not linked is told, once, at the end. */
+export declare const UNLINKED_PITCH: string[];
+/** Prove one flow with the coding agent: the line every ending names. */
+export declare const msgProveOneFlow: (url: string) => string;
+/**
+ * The closing lines for one tab's coverage, as `/status` reports it: the score, what is missing, the
+ * Harness gate in its own sentence, and the prompt for the coding agent. Pure.
+ */
+export declare function initCoverageLines(tab: Record<string, unknown> | undefined, url: string): string[];
+/**
+ * This project's runs and flows that will never reach the dashboard as things stand, one line each:
+ * not linked, no key for its host, flow sync off, or refused. A linked root's pending runs are left
+ * out, because the daemon sends them within seconds and saying so would be noise.
+ */
+export declare function strandedWorkLines(appDir: string): Promise<string[]>;
+/** What `init` hands its ending, once the connection is proved. */
+export interface FirstFlowContext {
+    appDir: string;
+    bridgePort: number;
+    pairingToken?: string | undefined;
+    url: string;
+    sessionId: string;
+    /** The proof came from a Reticle-owned browser, now closed: its own tab cannot be measured. */
+    leased: boolean;
+    openBrowser: boolean;
+    /** False for `--no-first-run`: connect, and say nothing more. */
+    firstRun: boolean;
+    json: boolean;
+}
+/**
+ * How `init` ends: the coverage score, the gaps and the agent prompt, the pitch when the project is
+ * not linked, then what will never reach the dashboard. Nothing is driven. Never throws.
+ */
+export declare function initFirstFlow(ctx: FirstFlowContext, say: (line: string) => void): Promise<{
+    flowSaved: boolean;
+}>;