@retrace-dev/cli 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,13 @@
+# @retrace-dev/cli
+
+Developer tooling for [Retrace](https://github.com/jordandru/retrace), a verifiable provenance ledger for AI-assisted software work.
+
+```bash
+npm exec --package=@retrace-dev/cli -- retrace doctor
+npm exec --package=@retrace-dev/cli -- retrace status --json
+npm exec --package=@retrace-dev/cli -- retrace-git install --project my-project
+```
+
+The package also installs `retrace-git`, `retrace-mcp`, `retrace-serve`, `retrace-export`, `retrace-github`, and `retrace-gdrive` binaries. Run the scoped `npm exec --package=@retrace-dev/cli -- retrace` form for doctor/status to avoid collisions with Android's unrelated `retrace` utility.
+
+Node.js 22 or newer is required by the local SQLite-backed server. See the [repository README](https://github.com/jordandru/retrace#readme) for configuration and cloud deployment.

package/dist/doctor.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { Actor, Credential } from "@retrace-dev/core";
+type Level = "pass" | "warn" | "fail";
+export type Finding = {
+    level: Level;
+    label: string;
+    detail: string;
+};
+export declare function missingSchema(remote: Record<string, unknown>, local?: {
+    event: string[];
+    location: string[];
+    artifact: string[];
+    actions: string[];
+}): string[];
+export declare function credentialAuthorization(credential: Credential, actor: Actor): Finding;
+export {};

package/dist/doctor.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/** retrace doctor — read-only preflight for the Git → Worker developer workflow. */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { Credential, renderProjectStatus, schemaSurface } from "@retrace-dev/core";
+import { commitToEvent, resolveHookToken } from "./git-hook.js";
+import { retraceHeaders } from "./remote-store.js";
+import { isMainModule } from "./is-main.js";
+const git = (repo, args) => execFileSync("git", ["-C", repo, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+const result = (level, label, detail) => ({ level, label, detail });
+export function missingSchema(remote, local = schemaSurface()) {
+    return Object.entries(local).flatMap(([group, keys]) => {
+        const seen = Array.isArray(remote[group]) ? remote[group] : [];
+        return keys.filter((key) => !seen.includes(key)).map((key) => `${group}.${key}`);
+    });
+}
+export function credentialAuthorization(credential, actor) {
+    if (credential.trust === "assert") {
+        const allowed = credential.allowed_actors ?? [];
+        return allowed.some((a) => a.type === actor.type && a.id === actor.id)
+            ? result("pass", "actor authorization", `${actor.type}/${actor.id} is allowed by ${credential.actor.id}`)
+            : result("fail", "actor authorization", `${actor.type}/${actor.id} is not in ${credential.actor.id}.allowed_actors; update RETRACE_CREDENTIALS before committing`);
+    }
+    return credential.actor.type === actor.type && credential.actor.id === actor.id
+        ? result("pass", "actor authorization", `${actor.type}/${actor.id} matches the pinned credential`)
+        : result("fail", "actor authorization", `HEAD is ${actor.type}/${actor.id}, but credential ${credential.actor.id} is pinned to ${credential.actor.type}/${credential.actor.id}`);
+}
+function loadCredential(cfg, env) {
+    if (!cfg.credential) {
+        const token = env.RETRACE_HOOK_TOKEN ?? env.RETRACE_TOKEN ?? cfg.token;
+        return { token, finding: token ? result("warn", "credential", "using an owner/file token; prefer a named scoped credential") : result("fail", "credential", "no hook token is configured") };
+    }
+    const file = env.RETRACE_CREDENTIALS_FILE ?? join(homedir(), ".retrace", "worker-credentials.json");
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (!Array.isArray(parsed))
+            throw new Error("expected a JSON array");
+        const raw = parsed.find((c) => c?.actor?.id === cfg.credential);
+        if (!raw)
+            throw new Error(`credential ${cfg.credential} was not found`);
+        const credential = Credential.parse(raw);
+        return { credential, token: resolveHookToken(cfg, env, file), finding: result("pass", "credential", `${cfg.credential} resolved from ${file}`) };
+    }
+    catch (e) {
+        return { finding: result("fail", "credential", `${e?.message ?? e}; check RETRACE_CREDENTIALS_FILE`) };
+    }
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0] === "status" ? "status" : "doctor";
+    if (args[0] && args[0] !== "doctor" && args[0] !== "status" && !args[0].startsWith(".") && !args[0].startsWith("/") && !existsSync(resolve(args[0]))) {
+        console.error("usage: retrace <doctor [repo] | status [project] [--json]>");
+        process.exit(2);
+        return;
+    }
+    const arg = command === "doctor" ? (args[0] === "doctor" ? args[1] : args[0]) : undefined;
+    let repo;
+    try {
+        repo = resolve(git(resolve(arg ?? process.cwd()), ["rev-parse", "--show-toplevel"]));
+    }
+    catch {
+        console.error("FAIL  repository — not inside a Git repository (or pass its path)");
+        process.exit(1);
+        return;
+    }
+    const findings = [];
+    const cfgPath = join(repo, ".retrace.json");
+    let cfg = {};
+    if (!existsSync(cfgPath))
+        findings.push(result("fail", "repository wiring", `${cfgPath} is missing; run retrace-git install --repo ${repo}`));
+    else
+        try {
+            cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+            findings.push(result("pass", "repository wiring", cfgPath));
+        }
+        catch (e) {
+            findings.push(result("fail", "repository wiring", `${cfgPath} is invalid JSON: ${e.message}`));
+        }
+    const gitDir = resolve(repo, git(repo, ["rev-parse", "--git-dir"]));
+    const hook = join(gitDir, "hooks", "post-commit");
+    const hookOk = existsSync(hook) && readFileSync(hook, "utf8").includes("# retrace-git hook");
+    findings.push(hookOk ? result("pass", "post-commit hook", hook) : result("fail", "post-commit hook", `not installed at ${hook}; run retrace-git install --repo ${repo}`));
+    const project = process.env.RETRACE_PROJECT ?? cfg.project ?? basename(repo);
+    const url = (process.env.RETRACE_URL ?? cfg.url ?? "").replace(/\/$/, "");
+    const auth = loadCredential(cfg, process.env);
+    findings.push(auth.finding);
+    if (command === "status") {
+        const selected = args[1] && !args[1].startsWith("--") ? args[1] : project;
+        if (!url) {
+            console.error("retrace status: RETRACE_URL or .retrace.json url is required");
+            process.exit(1);
+            return;
+        }
+        const res = await fetch(`${url}/projects/${encodeURIComponent(selected)}/status`, { headers: retraceHeaders(auth.token) });
+        if (!res.ok) {
+            console.error(`retrace status: HTTP ${res.status}: ${await res.text()}`);
+            process.exit(1);
+            return;
+        }
+        const status = await res.json();
+        console.log(args.includes("--json") ? JSON.stringify(status, null, 2) : renderProjectStatus(status));
+        return;
+    }
+    let headEvent;
+    try {
+        headEvent = commitToEvent(repo, "HEAD", { ...cfg, project, repoName: cfg.repoName });
+        if (auth.credential)
+            findings.push(credentialAuthorization(auth.credential, headEvent.actor));
+    }
+    catch (e) {
+        findings.push(result("fail", "HEAD", `could not inspect the current commit: ${e.message}`));
+    }
+    if (!url)
+        findings.push(result("warn", "deployment", "no RETRACE_URL or .retrace.json url; remote checks skipped"));
+    else {
+        const headers = retraceHeaders(auth.token);
+        try {
+            const res = await fetch(`${url}/api`, { headers: retraceHeaders() });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const api = await res.json();
+            const missing = missingSchema(api.schema ?? {});
+            findings.push(missing.length ? result("fail", "deployment schema", `would drop: ${missing.join(", ")}; deploy this build first`) : result("pass", "deployment schema", `${url} understands this build`));
+        }
+        catch (e) {
+            findings.push(result("fail", "deployment", `${url}/api is unreachable: ${e.message}`));
+        }
+        try {
+            const res = await fetch(`${url}/projects/${encodeURIComponent(project)}/verify`, { headers });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}: ${await res.text()}`);
+            const v = await res.json();
+            findings.push(v.ok ? result("pass", "ledger integrity", `${project}: ${v.checked} events verified`) : result("fail", "ledger integrity", `${project}: ${v.reason ?? "verification failed"}`));
+        }
+        catch (e) {
+            findings.push(result("fail", "ledger access", `${e.message}; check URL and credential`));
+        }
+        if (headEvent) {
+            const commit = headEvent.artifacts.find((a) => a.kind === "commit")?.id;
+            try {
+                const res = await fetch(`${url}/projects/${encodeURIComponent(project)}/events?artifact_id=${encodeURIComponent(commit ?? "")}`, { headers });
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}: ${await res.text()}`);
+                const events = await res.json();
+                findings.push(events.length ? result("pass", "HEAD delivery", `${commit} is event #${events.at(-1)?.seq}`) : result("warn", "HEAD delivery", `${commit} is not in the ledger; run retrace-git commit --repo ${repo} HEAD`));
+            }
+            catch (e) {
+                findings.push(result("fail", "HEAD delivery", e.message));
+            }
+        }
+    }
+    for (const f of findings)
+        console.log(`${f.level.toUpperCase()}  ${f.label} — ${f.detail}`);
+    const failed = findings.filter((f) => f.level === "fail").length, warned = findings.filter((f) => f.level === "warn").length;
+    console.log(`\n${failed ? "NOT READY" : "READY"} — ${findings.length - failed - warned} passed, ${warned} warnings, ${failed} failures`);
+    process.exit(failed ? 1 : 0);
+}
+if (isMainModule(import.meta.url))
+    main().catch((e) => { console.error("retrace doctor:", e.message ?? e); process.exit(1); });

package/dist/export-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/export-cli.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * retrace-export — signing keys, signed exports, offline verification.
+ *   retrace-export keygen [--print-private]           create ~/.retrace/signing-key.json if missing; print kid + public JWK
+ *   retrace-export export <project> [--artifact <id>] [--out file.json] [--report file.html]
+ *   retrace-export verify <bundle.json> [--pubkey <jwk.json|url>]
+ *   retrace-export share <project> [--artifact <id>] [--label ..] [--days n]      (local server must be running for the link to resolve)
+ * Uses the same store config as the MCP server (RETRACE_DB / RETRACE_URL+RETRACE_TOKEN).
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { buildExportBundle, verifyExportBundle, renderReportHtml, parseSigningKey, newShareId } from "@retrace-dev/core";
+import { makeStore } from "./index.js";
+import { RemoteStore } from "./remote-store.js";
+import { ensureSigningKey } from "./keys.js";
+import { isMainModule } from "./is-main.js";
+function parseArgs(argv) {
+    const flags = {};
+    const pos = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith("--")) {
+            const n = argv[i + 1];
+            if (n && !n.startsWith("--")) {
+                flags[a.slice(2)] = n;
+                i++;
+            }
+            else
+                flags[a.slice(2)] = true;
+        }
+        else
+            pos.push(a);
+    }
+    return { flags, pos };
+}
+async function main() {
+    const { flags, pos } = parseArgs(process.argv.slice(2));
+    const cmd = pos[0];
+    if (cmd === "keygen") {
+        const k = await ensureSigningKey();
+        console.log(`${k.created ? "created" : "existing"} signing key at ${k.path}\nkid: ${k.kid}\npublic JWK: ${JSON.stringify(k.publicKey)}`);
+        if (flags["print-private"])
+            console.log(`\nRETRACE_SIGNING_KEY='${JSON.stringify(k.privateKey)}'`);
+        else
+            console.log(`\nFor the Cloudflare Worker: wrangler secret put RETRACE_SIGNING_KEY   (paste the private JWK; print it with --print-private)`);
+        return;
+    }
+    if (cmd === "export") {
+        const project = pos[1];
+        if (!project)
+            throw new Error("usage: retrace-export export <project>");
+        const store = makeStore();
+        let bundle;
+        if (store instanceof RemoteStore)
+            bundle = await store.export({ project, artifact_id: flags.artifact });
+        else {
+            const key = parseSigningKey(process.env.RETRACE_SIGNING_KEY) ?? (await ensureSigningKey()).privateKey;
+            bundle = await buildExportBundle(store, { project, artifact_id: flags.artifact }, { signingKey: key, issuerName: process.env.RETRACE_ISSUER });
+        }
+        const out = flags.out ?? `retrace-${project}${flags.artifact ? "-" + String(flags.artifact).replace(/[^\w.-]+/g, "_") : ""}.json`;
+        writeFileSync(out, JSON.stringify(bundle, null, 2));
+        console.log(`wrote ${out} — ${bundle.events.length} events, chain ${bundle.chain.ok ? "intact" : "BROKEN"}, ${bundle.signature ? "signed kid " + bundle.issuer.kid : "UNSIGNED"}`);
+        if (flags.report) {
+            writeFileSync(flags.report, renderReportHtml(bundle, await verifyExportBundle(bundle)));
+            console.log(`wrote ${flags.report}`);
+        }
+        return;
+    }
+    if (cmd === "verify") {
+        const file = pos[1];
+        if (!file)
+            throw new Error("usage: retrace-export verify <bundle.json> [--pubkey jwk.json|url]");
+        const bundle = JSON.parse(readFileSync(file, "utf8"));
+        let trusted;
+        if (flags.pubkey) {
+            const src = String(flags.pubkey);
+            const raw = /^https?:/.test(src) ? await (await fetch(src)).json() : JSON.parse(readFileSync(src, "utf8"));
+            trusted = raw.public_key ?? raw;
+        }
+        const v = await verifyExportBundle(bundle, trusted);
+        const ok = v.signature === "valid" && v.events_intact && v.links_consistent && v.chain_ok_at_export;
+        console.log(`${ok ? "VALID" : "NOT VALID"} — signature: ${v.signature}${v.kid ? " (kid " + v.kid + (trusted ? ", trusted key" : ", key embedded in bundle") + ")" : ""}; events intact: ${v.events_intact}; links: ${v.links_consistent}; chain ok at export: ${v.chain_ok_at_export}; ${bundle.events.length} events`);
+        for (const p of v.problems)
+            console.log("  - " + p);
+        process.exit(ok ? 0 : 2);
+    }
+    if (cmd === "share") {
+        const project = pos[1];
+        if (!project)
+            throw new Error("usage: retrace-export share <project>");
+        const store = makeStore();
+        const body = { project, artifact_id: flags.artifact, label: flags.label, expires_in_days: flags.days ? Number(flags.days) : undefined };
+        if (store instanceof RemoteStore) {
+            const r = await store.share(body);
+            console.log(`${r.url}\nreport: ${r.url}/report`);
+            return;
+        }
+        const id = newShareId();
+        const now = new Date();
+        await store.createShare({ id, project, artifact_id: body.artifact_id, label: body.label, created_at: now.toISOString(), expires_at: body.expires_in_days ? new Date(now.getTime() + body.expires_in_days * 86400000).toISOString() : undefined });
+        const base = process.env.RETRACE_PUBLIC_URL ?? `http://localhost:${process.env.RETRACE_PORT ?? 7777}`;
+        console.log(`${base}/s/${id}\nreport: ${base}/s/${id}/report`);
+        return;
+    }
+    console.log("retrace-export <keygen|export <project>|verify <bundle.json>|share <project>> [--artifact id] [--out f] [--report f.html] [--pubkey jwk|url] [--label s] [--days n]");
+}
+if (isMainModule(import.meta.url))
+    main().catch((e) => { console.error("retrace-export:", e.message ?? e); process.exit(1); });

package/dist/gdrive-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/gdrive-cli.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * retrace-gdrive — Google Drive adapter helpers (the Apps Script forwarder is the zero-infra path; this is for backfills & testing).
+ *   retrace-gdrive backfill --token <OAuth access token> [--project p] [--folder <id>] [--since 2026-08-01] [--max 1000]
+ *        queries the Drive Activity API directly (scope drive.activity.readonly; e.g. `gcloud auth print-access-token`
+ *        or OAuth Playground) and logs the mapped events. Actor emails resolve via People API when the token allows.
+ *   retrace-gdrive replay <payload.json> [--project p]      map a saved forwarder payload / activity.query response and log it
+ * Store config: RETRACE_DB (local) or RETRACE_URL(+RETRACE_TOKEN).
+ */
+import { readFileSync } from "node:fs";
+import { mapDriveActivities, appendEvent, describeEvent } from "@retrace-dev/core";
+import { makeStore } from "./index.js";
+import { RemoteStore } from "./remote-store.js";
+import { isMainModule } from "./is-main.js";
+function parseArgs(argv) {
+    const flags = {};
+    const pos = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith("--")) {
+            const n = argv[i + 1];
+            if (n && !n.startsWith("--")) {
+                flags[a.slice(2)] = n;
+                i++;
+            }
+            else
+                flags[a.slice(2)] = true;
+        }
+        else
+            pos.push(a);
+    }
+    return { flags, pos };
+}
+async function logAll(payload, project) {
+    const inputs = mapDriveActivities({ ...payload, project: project ?? payload.project }, "google-drive");
+    const store = makeStore();
+    let n = 0, d = 0;
+    for (const input of inputs) {
+        const r = store instanceof RemoteStore ? await store.append(input) : await appendEvent(store, input);
+        r.deduped ? d++ : (n++, console.log(describeEvent(r.event)));
+    }
+    return { logged: n, deduped: d, mapped: inputs.length };
+}
+async function main() {
+    const { flags, pos } = parseArgs(process.argv.slice(2));
+    const cmd = pos[0];
+    const project = flags.project ?? process.env.RETRACE_PROJECT;
+    if (cmd === "replay") {
+        const raw = JSON.parse(readFileSync(pos[1], "utf8"));
+        const payload = Array.isArray(raw.activities) ? raw : { activities: raw };
+        const r = await logAll(payload, project);
+        console.log(`replay: ${r.mapped} mapped, ${r.logged} logged, ${r.deduped} deduped`);
+        return;
+    }
+    if (cmd === "backfill") {
+        const token = flags.token ?? process.env.GOOGLE_ACCESS_TOKEN;
+        if (!token)
+            throw new Error("--token <OAuth access token> required (scope drive.activity.readonly)");
+        const since = flags.since ? new Date(String(flags.since)).toISOString() : new Date(Date.now() - 7 * 86400000).toISOString();
+        const max = Number(flags.max ?? 1000);
+        const acts = [];
+        let pageToken;
+        do {
+            const body = { filter: `time >= "${since}"`, pageSize: 100, ...(pageToken ? { pageToken } : {}), ...(flags.folder ? { ancestorName: `items/${flags.folder}` } : {}) };
+            const res = await fetch("https://driveactivity.googleapis.com/v2/activity:query", { method: "POST", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, body: JSON.stringify(body) });
+            if (!res.ok)
+                throw new Error(`Drive Activity ${res.status}: ${await res.text()}`);
+            const j = await res.json();
+            acts.push(...(j.activities ?? []));
+            pageToken = j.nextPageToken;
+        } while (pageToken && acts.length < max);
+        const actors = {};
+        const names = new Set();
+        for (const a of acts)
+            for (const x of a.actors ?? []) {
+                const pn = (x.user ?? x.impersonation?.impersonatedUser)?.knownUser?.personName;
+                if (pn)
+                    names.add(pn);
+            }
+        for (const pn of names) {
+            try {
+                const res = await fetch(`https://people.googleapis.com/v1/${pn}?personFields=emailAddresses,names`, { headers: { authorization: `Bearer ${token}` } });
+                if (res.ok) {
+                    const p = await res.json();
+                    actors[pn] = { email: p.emailAddresses?.[0]?.value, name: p.names?.[0]?.displayName };
+                }
+            }
+            catch { }
+        }
+        const r = await logAll({ activities: acts, actors, source: "cli" }, project);
+        console.log(`backfill: ${acts.length} activities, ${r.mapped} mapped, ${r.logged} logged, ${r.deduped} deduped`);
+        return;
+    }
+    console.log("retrace-gdrive <backfill --token T [--folder id] [--since date] | replay <payload.json>> [--project name]");
+}
+if (isMainModule(import.meta.url))
+    main().catch((e) => { console.error("retrace-gdrive:", e.message ?? e); process.exit(1); });