summer-engine 4.3.0 → 4.5.0

package/dist/core/telemetry.js

@@ -2,20 +2,33 @@
  * Usage beacons for the local MCP server. Fire-and-forget, never blocks, never throws.
  *
  * - One session ping per MCP server lifetime (mcp_session_start), on the
- *   first tool call, with the host app's name from the MCP handshake.
+ *   first tool call, with the host app's name from the MCP handshake and
+ *   this machine's install id, so the anonymous first-run line (below) joins
+ *   the account.
  * - One line per local tool call (mcp_tool_call): the tool name, the
  *   Summer operation it ran, success, duration, the host app's name from the
- *   MCP handshake, and the tool surface and profile. Nothing else: no
+ *   MCP handshake, and the tool surface and profile, plus the closed-shape
+ *   fields of usage-fields.ts (project id hash, template, game clients
+ *   started, engine state on engine_not_running). Nothing else: no
  *   arguments, no results, no project or file names.
+ * - Once per machine, the first `summer` command (any, `summer mcp` too)
+ *   prints a short notice to stderr and sends one anonymous line
+ *   (cli_first_run): the install id, the command name, the agent app and the
+ *   operating system. It is the only line sent without an account.
  *
- * Both go to /api/mcp/log-local-call, only when signed in (the account token
- * attributes them), and never when SUMMER_NO_TELEMETRY=1 or DO_NOT_TRACK=1.
- * The endpoint always returns allowed:true and never gates; the response is
- * ignored.
+ * The session and call lines go to /api/mcp/log-local-call only when signed
+ * in (the account token attributes them). Nothing is sent when
+ * SUMMER_NO_TELEMETRY=1 or DO_NOT_TRACK=1. The endpoint always returns
+ * allowed:true and never gates; the response is ignored.
  */
-import { currentMcpClient, isTelemetryDisabled, summerRequestHeaders } from "./agent-host.js";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { currentMcpClient, isTelemetryDisabled, resolveAgentHost, summerRequestHeaders } from "./agent-host.js";
 import { getAuthToken } from "./auth.js";
 import { resolveGatewayUrl } from "./config.js";
+import { getInstallId } from "./feedback/client.js";
+import { readStoreText, writeStoreText } from "./store.js";
+import { usageLineFields } from "./usage-fields.js";
 export { isTelemetryDisabled };
 const TELEMETRY_PATH = "/api/mcp/log-local-call";
 const TIMEOUT_MS = 5000;
@@ -34,7 +47,10 @@ export function recordMcpSession() {
         return;
     pinged = true;
     const mcpClient = currentMcpClient()?.name;
-    send({ client: "summer-cli", event: "mcp_session_start", ...(mcpClient ? { mcpClient: mcpClient.slice(0, 64) } : {}) });
+    void (async () => {
+        const installId = await getInstallId();
+        await postUsage({ client: "summer-cli", event: "mcp_session_start", ...(mcpClient ? { mcpClient: mcpClient.slice(0, 64) } : {}), installId });
+    })();
 }
 const ERROR_CODE = /^[a-z][a-z0-9_]{0,63}$/;
 /**
@@ -67,6 +83,7 @@ export function toolErrorCode(result, fallback) {
 export function recordLocalToolCall(call) {
     if (isTelemetryDisabled() || !TOOL_NAME.test(call.tool))
         return;
+    const error = !call.ok && call.error && ERROR_CODE.test(call.error) ? call.error : null;
     send({
         client: "summer-cli",
         event: "mcp_tool_call",
@@ -76,19 +93,20 @@ export function recordLocalToolCall(call) {
         ...(call.surfaceVersion ? { surfaceVersion: call.surfaceVersion } : {}),
         ...(call.profile ? { profile: call.profile } : {}),
         ok: call.ok,
-        ...(!call.ok && call.error && ERROR_CODE.test(call.error) ? { error: call.error } : {}),
+        ...(error ? { error } : {}),
         durationMs: Math.max(0, Math.round(call.durationMs)),
-    });
+    }, call.usage ?? {}, error);
 }
-function send(body) {
+function send(body, usage, error) {
     // Void-discarded so the caller never accidentally awaits us.
-    void postUsage(body);
+    void (async () => postUsage({ ...body, ...(await usageLineFields(usage, error)) }))();
 }
 /** POST one usage line with the account token; resolves when sent or given up. Never throws. */
-export async function postUsage(body, timeoutMs = TIMEOUT_MS) {
+export async function postUsage(body, timeoutMs = TIMEOUT_MS, options = {}) {
     try {
-        const token = await getAuthToken();
-        if (!token)
+        // The first-run line is the one line sent without an account token.
+        const token = options.anonymous ? null : await getAuthToken();
+        if (!token && !options.anonymous)
             return; // unauthenticated usage is allowed; we just can't attribute it
         // Resolved per call, not at import: the gateway the token belongs to is
         // whatever env/config says NOW (see config.resolveGatewayUrl).
@@ -101,7 +119,7 @@ export async function postUsage(body, timeoutMs = TIMEOUT_MS) {
                 signal: ctrl.signal,
                 headers: {
                     ...summerRequestHeaders(),
-                    Authorization: `Bearer ${token}`,
+                    ...(token ? { Authorization: `Bearer ${token}` } : {}),
                     "Content-Type": "application/json",
                 },
                 body: JSON.stringify(body),
@@ -115,6 +133,64 @@ export async function postUsage(body, timeoutMs = TIMEOUT_MS) {
         // never throws — telemetry is best-effort
     }
 }
+const NOTICE_MARKER_FILE = "telemetry-notice";
+const COMMAND = /^[a-z][a-z0-9_]{0,79}$/;
+const BEACON = fileURLToPath(new URL("./cli-usage-beacon.js", import.meta.url));
+/** The one-time notice, printed to stderr (never stdout: `summer mcp` speaks MCP there). */
+export const TELEMETRY_NOTICE = [
+    "Summer collects usage data to improve its tools: which commands and tools run, whether they worked, and which agent app ran them.",
+    "No prompts, code, file names or project names. Opt out: SUMMER_NO_TELEMETRY=1",
+    "Details: https://github.com/summerengine/summer#telemetry",
+].join("\n");
+/** CI runs and this repo's own tests are not people trying Summer. */
+function automatedRun(env) {
+    const on = (value) => !!value && value !== "0" && value.toLowerCase() !== "false";
+    return on(env.CI) || on(env.VITEST);
+}
+/**
+ * The first `summer` command on this machine: print the notice once, then
+ * send one anonymous cli_first_run line (install id, command name, agent
+ * app, operating system). Nothing when opted out, in CI, or when the marker
+ * cannot be written (no line without the notice). Returns whether it ran.
+ */
+export async function noteFirstRun(command, deps = {}) {
+    const env = deps.env ?? process.env;
+    try {
+        if (isTelemetryDisabled(env) || automatedRun(env))
+            return false;
+        if ((await readStoreText(NOTICE_MARKER_FILE)) !== null)
+            return false;
+        await writeStoreText(NOTICE_MARKER_FILE, new Date().toISOString());
+        (deps.write ?? ((text) => process.stderr.write(text)))(`${TELEMETRY_NOTICE}\n\n`);
+        const body = {
+            client: "summer-cli",
+            event: "cli_first_run",
+            installId: await getInstallId(),
+            ...(COMMAND.test(command) ? { command } : {}),
+            mcpClient: resolveAgentHost(env, undefined).id,
+            os: process.platform,
+        };
+        (deps.send ?? sendAnonymous)(body);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A detached child sends it, so no command waits for the network or loses it to process.exit(). */
+function sendAnonymous(body) {
+    try {
+        spawn(process.execPath, [BEACON, JSON.stringify(body), "--anonymous"], {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+            env: { ...process.env, NODE_OPTIONS: (process.env.NODE_OPTIONS ?? "").replace(/--inspect\S*/g, "").trim() },
+        }).unref();
+    }
+    catch {
+        // best-effort
+    }
+}
 /**
  * Reset the once-per-session guard. Test-only.
  */

package/dist/core/templates.d.ts

@@ -95,3 +95,23 @@ export interface MaterializedTemplate {
  * a half-fetched template never looks like a project.
  */
 export declare function materializePinnedTemplate(entry: TemplateEntry, opts: MaterializeOptions): MaterializedTemplate;
+/** The codeload tarball URL for a github.com pin, or null when the pin is not
+ *  a GitHub repo (then only git can fetch it). */
+export declare function githubTarballUrl(pin: TemplatePin): string | null;
+export interface FetchPinnedOptions extends MaterializeOptions {
+    /** The HTTP GET. Default: global fetch. Tests inject one. */
+    fetchTarball?: (url: string, signal: AbortSignal) => Promise<Response>;
+    /** Tarball URL for a pin, null for git only. Default: githubTarballUrl. Tests
+     *  override it so a local (git-fetchable) pin can also take the tarball path. */
+    tarballUrl?: (pin: TemplatePin) => string | null;
+}
+/**
+ * Same contract as materializePinnedTemplate, without git when it can: a
+ * github.com pin is downloaded as the codeload tarball of exactly `commit`
+ * into a hidden sibling of `targetDir`, the tree digest is recomputed from the
+ * archive (same formula, same strict compare), and only a match is renamed
+ * into place. Any tarball failure removes the staging dir and falls back to
+ * the git path, so a mismatch still ends in git's own strict check.
+ * keepGit goes straight to git (a tarball has no .git).
+ */
+export declare function fetchPinnedTemplate(entry: TemplateEntry, opts: FetchPinnedOptions): Promise<MaterializedTemplate>;

package/dist/core/templates.js

@@ -12,15 +12,21 @@
  *      recompute `tree_digest` with the documented formula and REFUSE on any
  *      mismatch, then check out the pinned tree (detached unless keepGit).
  *
+ * `fetchPinnedTemplate` first tries the same pin as a GitHub tarball (no git,
+ * so a clean Mac never sees the Command Line Tools dialog), verifies the same
+ * digest from the archive, and falls back to the git path on any failure.
+ *
  * A default branch is never consulted. Nothing here lists a GitHub org.
  *
  * Built-in templates (`builtin: true`) carry no pin; the CLI generates them
  * in-process. This module only identifies them.
  */
 import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, symlinkSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { pipeline, Readable } from "node:stream";
+import { createGunzip } from "node:zlib";
 import { PACKAGE_ROOT } from "./package-root.js";
 const REGISTRY_RELPATH = join("registry", "generated", "templates-registry.json");
 let cache = null;
@@ -238,3 +244,294 @@ export function materializePinnedTemplate(entry, opts) {
         rmSync(join(opts.targetDir, ".git"), { recursive: true, force: true });
     return { commit: pin.commit, tree_digest: pin.tree_digest };
 }
+// ---------- tarball (no git) ----------
+/** The codeload tarball URL for a github.com pin, or null when the pin is not
+ *  a GitHub repo (then only git can fetch it). */
+export function githubTarballUrl(pin) {
+    const m = /^https:\/\/github\.com\/([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/.exec(pin.repo);
+    if (!m || !/^[0-9a-f]{40}$/.test(pin.commit))
+        return null;
+    return `https://codeload.github.com/${m[1]}/${m[2]}/tar.gz/${pin.commit}`;
+}
+/**
+ * Same contract as materializePinnedTemplate, without git when it can: a
+ * github.com pin is downloaded as the codeload tarball of exactly `commit`
+ * into a hidden sibling of `targetDir`, the tree digest is recomputed from the
+ * archive (same formula, same strict compare), and only a match is renamed
+ * into place. Any tarball failure removes the staging dir and falls back to
+ * the git path, so a mismatch still ends in git's own strict check.
+ * keepGit goes straight to git (a tarball has no .git).
+ */
+export async function fetchPinnedTemplate(entry, opts) {
+    const pin = entry.pin;
+    if (!pin)
+        throw new Error(`${entry.id} is a built-in template and has no pin to materialize.`);
+    if (existsSync(opts.targetDir))
+        throw new Error(`Directory already exists: ${opts.targetDir}`);
+    const url = opts.keepGit ? null : (opts.tarballUrl ?? githubTarballUrl)(pin);
+    if (!url)
+        return materializePinnedTemplate(entry, opts);
+    const log = opts.log ?? (() => { });
+    const target = resolve(opts.targetDir);
+    const staging = join(dirname(target), `.${basename(target)}.summer-download-${randomBytes(4).toString("hex")}`);
+    try {
+        mkdirSync(dirname(target), { recursive: true });
+        mkdirSync(staging);
+        log(`Downloading ${pin.repo} at ${pin.commit.slice(0, 12)} ...`);
+        const fetcher = opts.fetchTarball ?? ((u, signal) => fetch(u, { signal }));
+        const actual = await downloadTree(url, staging, fetcher);
+        if (actual !== pin.tree_digest) {
+            throw new Error(`tree digest mismatch: archive ${actual.slice(0, 12)}, pin ${pin.tree_digest.slice(0, 12)}`);
+        }
+        log(`Verified tree digest ${actual.slice(0, 12)}`);
+        if (existsSync(target))
+            throw new Error(`Directory already exists: ${opts.targetDir}`);
+        renameSync(staging, target);
+        return { commit: pin.commit, tree_digest: pin.tree_digest };
+    }
+    catch (err) {
+        rmSync(staging, { recursive: true, force: true });
+        const why = (err instanceof Error ? err.message : String(err)).replace(/\s+/g, " ");
+        log(`Tarball download failed (${why}); falling back to git.`);
+        return materializePinnedTemplate(entry, opts);
+    }
+}
+/** Download, gunzip and unpack a GitHub tarball into `staging` as a stream.
+ *  fetchTimeoutSeconds() bounds each wait for bytes, not the whole download:
+ *  a big template on a slow link keeps going while bytes arrive. Returns the
+ *  tree digest of the archive. */
+async function downloadTree(url, staging, fetcher) {
+    const seconds = fetchTimeoutSeconds();
+    const ctrl = new AbortController();
+    let timer = setTimeout(() => ctrl.abort(), seconds * 1000);
+    const stillGoing = () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => ctrl.abort(), seconds * 1000);
+    };
+    const gunzip = createGunzip();
+    try {
+        const res = await fetcher(url, ctrl.signal);
+        if (res.status !== 200 || !res.body)
+            throw new Error(`HTTP ${res.status}`);
+        const body = Readable.fromWeb(res.body);
+        body.on("data", stillGoing);
+        // Errors on either side end the gunzip stream early; extractTar then fails.
+        pipeline(body, gunzip, () => { });
+        return await extractTar(gunzip, staging);
+    }
+    catch (err) {
+        if (ctrl.signal.aborted)
+            throw new Error(`no data for ${seconds}s`);
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+        ctrl.abort();
+        gunzip.destroy();
+    }
+}
+/** Reads exact byte counts from a stream of chunks; one file at a time is the
+ *  most it ever holds. */
+function byteReader(source) {
+    const it = source[Symbol.asyncIterator]();
+    let parts = [];
+    let have = 0;
+    return async (n) => {
+        if (n === 0)
+            return Buffer.alloc(0);
+        while (have < n) {
+            const r = await it.next();
+            if (r.done)
+                throw new Error("archive ended early");
+            parts.push(r.value);
+            have += r.value.length;
+        }
+        const all = parts.length === 1 ? parts[0] : Buffer.concat(parts, have);
+        const rest = all.subarray(n);
+        parts = rest.length ? [rest] : [];
+        have = rest.length;
+        return all.subarray(0, n);
+    };
+}
+function cstr(b) {
+    const i = b.indexOf(0);
+    return i < 0 ? b : b.subarray(0, i);
+}
+/** A tar numeric field: octal text, or base-256 when the high bit is set. */
+function tarNumber(field) {
+    if (field[0] & 0x80) {
+        if (field[0] === 0xff)
+            throw new Error("negative number in tar header");
+        let n = field[0] & 0x7f;
+        for (let i = 1; i < field.length; i++)
+            n = n * 256 + field[i];
+        if (!Number.isSafeInteger(n))
+            throw new Error("number too large in tar header");
+        return n;
+    }
+    const s = cstr(field).toString("latin1").trim();
+    if (s === "")
+        return 0;
+    if (!/^[0-7]+$/.test(s))
+        throw new Error(`bad number in tar header: ${JSON.stringify(s)}`);
+    return parseInt(s, 8);
+}
+/** pax records: "<len> <key>=<value>\n", values kept as bytes. */
+function parsePax(body, into) {
+    let pos = 0;
+    while (pos < body.length) {
+        const sp = body.indexOf(0x20, pos);
+        const len = sp < 0 ? NaN : Number(body.subarray(pos, sp).toString("latin1"));
+        if (!Number.isSafeInteger(len) || pos + len > body.length || sp >= pos + len - 1) {
+            throw new Error("bad pax header");
+        }
+        const rec = body.subarray(sp + 1, pos + len - 1);
+        const eq = rec.indexOf(0x3d);
+        if (eq < 0)
+            throw new Error("bad pax header");
+        into.set(rec.subarray(0, eq).toString("utf8"), rec.subarray(eq + 1));
+        pos += len;
+    }
+}
+/** git's blob object id: sha1("blob <size>\0" + bytes). */
+function blobId(data) {
+    return createHash("sha1").update(`blob ${data.length}\0`).update(data).digest("hex");
+}
+const C_ESCAPES = { 7: "a", 8: "b", 9: "t", 10: "n", 11: "v", 12: "f", 13: "r", 0x22: '"', 0x5c: "\\" };
+/** A path as `git ls-tree` prints it by default (core.quotePath=true): C-quoted
+ *  when it has a control byte, `"`, `\`, DEL or any byte >= 0x80. */
+function quoteGitPath(path) {
+    if (!path.some((b) => b < 0x20 || b === 0x22 || b === 0x5c || b >= 0x7f))
+        return path;
+    let out = '"';
+    for (const b of path) {
+        if (C_ESCAPES[b])
+            out += "\\" + C_ESCAPES[b];
+        else if (b < 0x20 || b >= 0x7f)
+            out += "\\" + b.toString(8).padStart(3, "0");
+        else
+            out += String.fromCharCode(b);
+    }
+    return Buffer.from(out + '"', "latin1");
+}
+/**
+ * Unpack a git-archive tar (what codeload serves) into `staging` and return
+ * the documented tree digest of its contents. The top-level `<repo>-<sha>/`
+ * directory is stripped. Anything unexpected throws: entry types other than
+ * file/dir/symlink, absolute or `..` paths, a second top-level directory, a
+ * path through a symlink, or a duplicate path. Nothing is written outside
+ * `staging`.
+ */
+async function extractTar(source, staging) {
+    const read = byteReader(source);
+    const readPadded = async (size) => {
+        const data = await read(size);
+        await read((512 - (size % 512)) % 512);
+        return data;
+    };
+    const lines = [];
+    const realDirs = new Set([staging]);
+    // Create each missing directory under staging; refuse to pass through a
+    // symlink or a file (lstat asks the filesystem, so case folding is covered).
+    const ensureDir = (parts) => {
+        let p = staging;
+        for (const part of parts) {
+            p = join(p, part);
+            if (realDirs.has(p))
+                continue;
+            const st = lstatSync(p, { throwIfNoEntry: false });
+            if (!st)
+                mkdirSync(p);
+            else if (!st.isDirectory())
+                throw new Error(`archive path passes through a non-directory: ${parts.join("/")}`);
+            realDirs.add(p);
+        }
+    };
+    let root = null;
+    let pax = new Map();
+    let longName = null;
+    let longLink = null;
+    for (;;) {
+        const h = await read(512);
+        if (h.every((b) => b === 0)) {
+            if (!(await read(512)).every((b) => b === 0))
+                throw new Error("bad tar end marker");
+            break;
+        }
+        let sum = 0;
+        for (let i = 0; i < 512; i++)
+            sum += i >= 148 && i < 156 ? 0x20 : h[i];
+        if (sum !== tarNumber(h.subarray(148, 156)))
+            throw new Error("bad tar header checksum");
+        const type = h[156] === 0 ? "0" : String.fromCharCode(h[156]);
+        let size = tarNumber(h.subarray(124, 136));
+        if (type === "x" || type === "g" || type === "L" || type === "K") {
+            const body = await readPadded(size);
+            if (type === "x")
+                parsePax(body, pax);
+            else if (type === "L")
+                longName = cstr(body);
+            else if (type === "K")
+                longLink = cstr(body);
+            continue; // "g": GitHub puts the commit id there; nothing to apply
+        }
+        const ustar = h.subarray(257, 263).toString("latin1") === "ustar\0";
+        const prefix = ustar ? cstr(h.subarray(345, 500)) : Buffer.alloc(0);
+        const shortName = cstr(h.subarray(0, 100));
+        const name = pax.get("path") ?? longName ?? (prefix.length ? Buffer.concat([prefix, Buffer.from("/"), shortName]) : shortName);
+        const link = pax.get("linkpath") ?? longLink ?? cstr(h.subarray(157, 257));
+        const paxSize = pax.get("size");
+        if (paxSize) {
+            size = Number(paxSize.toString("latin1"));
+            if (!Number.isSafeInteger(size) || size < 0)
+                throw new Error("bad pax size");
+        }
+        pax = new Map();
+        longName = longLink = null;
+        // Strip the single top-level `<repo>-<sha>/` directory.
+        const slash = name.indexOf(0x2f);
+        const top = slash < 0 ? name : name.subarray(0, slash);
+        if (root === null)
+            root = top;
+        if (!top.equals(root) || top.length === 0)
+            throw new Error("archive is not a single top-level directory");
+        let rel = slash < 0 ? Buffer.alloc(0) : name.subarray(slash + 1);
+        while (rel.length && rel[rel.length - 1] === 0x2f)
+            rel = rel.subarray(0, rel.length - 1);
+        const parts = rel.length ? rel.toString("utf8").split("/") : [];
+        for (const part of parts) {
+            if (part === "" || part === "." || part === ".." || (process.platform === "win32" && /[\\:]/.test(part))) {
+                throw new Error(`unsafe path in archive: ${JSON.stringify(rel.toString("utf8"))}`);
+            }
+        }
+        if (parts.length === 0 && type !== "5")
+            throw new Error("file outside the archive's top-level directory");
+        const dest = join(staging, ...parts);
+        if (type === "0") {
+            const data = await readPadded(size);
+            ensureDir(parts.slice(0, -1));
+            const mode = tarNumber(h.subarray(100, 108)) & 0o111 ? 0o755 : 0o644;
+            writeFileSync(dest, data, { flag: "wx", mode }); // wx: never follows or overwrites
+            lines.push({ path: rel, oid: blobId(data) });
+        }
+        else if (type === "5") {
+            await readPadded(size);
+            ensureDir(parts);
+        }
+        else if (type === "2") {
+            await readPadded(size);
+            ensureDir(parts.slice(0, -1));
+            symlinkSync(link.toString("utf8"), dest);
+            lines.push({ path: rel, oid: blobId(link) });
+        }
+        else {
+            throw new Error(`unsupported tar entry type ${JSON.stringify(type)}`);
+        }
+    }
+    // Bytewise path order equals `git ls-tree -r` order.
+    lines.sort((a, b) => Buffer.compare(a.path, b.path));
+    const hash = createHash("sha256");
+    for (const l of lines)
+        hash.update(`${l.oid} `).update(quoteGitPath(l.path)).update("\n");
+    return hash.digest("hex");
+}

package/dist/core/tool-profiles.d.ts

@@ -4,11 +4,11 @@
  * which writes a profile into an agent's MCP entry. `full` is today's
  * surface exactly and the default, so existing configs keep it.
  */
-export declare const TOOLSETS: readonly ["core", "assets", "tools", "engine", "ui", "ship", "uploads", "apps", "board", "grow", "studio", "cloud", "other"];
+export declare const TOOLSETS: readonly ["core", "assets", "tools", "engine", "ui", "ship", "uploads", "apps", "board", "grow", "studio", "cloud", "projects", "other"];
 export type Toolset = (typeof TOOLSETS)[number];
 export declare const PROFILES: {
     /** Every tool, local and hosted (today's surface). */
-    readonly full: readonly ["core", "assets", "tools", "engine", "ui", "ship", "uploads", "apps", "board", "grow", "studio", "cloud", "other"];
+    readonly full: readonly ["core", "assets", "tools", "engine", "ui", "ship", "uploads", "apps", "board", "grow", "studio", "cloud", "projects", "other"];
     /** Summer Engine creators: engine, generation and the store. Fits clients with a 128-tool limit. */
     readonly engine: readonly ["core", "assets", "engine", "ship"];
     /** Any engine or none: generation, the asset library, account and library search. No engine tools. */

package/dist/core/tool-profiles.js

@@ -17,6 +17,7 @@ export const TOOLSETS = [
     "grow",
     "studio",
     "cloud",
+    "projects",
     "other",
 ];
 export const PROFILES = {

package/dist/core/usage-fields.d.ts

@@ -0,0 +1,41 @@
+export interface UsageFields {
+    projectIdHash?: string;
+    templateId?: string;
+    templateTags?: string[];
+    instanceCount?: number;
+}
+export interface EngineState {
+    desktopInstalled: boolean;
+    engineRunning: boolean;
+    projectOpen: boolean;
+    signedIn: boolean;
+}
+/** Only the closed shapes above survive; everything else is dropped. */
+export declare function cleanUsageFields(fields: Record<string, unknown>): UsageFields;
+/** A tool or command noted fields for its usage line; never throws. */
+export declare function noteToolUsage(fields: UsageFields): void;
+/** The fields noted in this process (the CLI line), with the bound project. */
+export declare function processUsageFields(): UsageFields;
+/** The engine connection bound this project (api-client.ts connect and rebind). */
+export declare function noteBoundProject(projectIdHash: string | undefined): void;
+export declare function boundProject(): string | undefined;
+/** The library slug for a catalog template id or slug, else null. */
+export declare function catalogTemplateSlug(idOrSlug: string): string | null;
+/** A catalog template's library domains (`facets.domains`), e.g. ["2d", "platformer"]. */
+export declare function templateTags(slug: string): string[];
+/**
+ * The catalog template the project with this hash started from: the running
+ * editor's registry entry gives its folder, `.summer/project.json` the
+ * template. Cached per hash; null when unknown or not a catalog template.
+ */
+export declare function templateForProject(projectIdHash: string): Promise<string | null>;
+/** What is true on this machine when the engine could not be reached. Local files only. */
+export declare function engineState(): Promise<EngineState>;
+/**
+ * The extra fields of one usage line: what the call noted, else the bound
+ * project and its template, and the engine state for engine_not_running.
+ * Never throws.
+ */
+export declare function usageLineFields(noted: UsageFields, error?: string | null): Promise<Record<string, unknown>>;
+/** Test-only: forget notes, the bound project and the template cache. */
+export declare function _resetUsageFieldsForTests(): void;