infinite-tag 0.1.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,142 @@
+# infinite-tag
+
+Add analytics to your web app with one command. `infinite-tag` installs
+**Google Analytics 4**, **PostHog**, and the **X (Twitter) Pixel** into your
+codebase — using only your **public** keys, with changes that are idempotent and
+fully reversible.
+
+You run it **inside your own web app's repository**. It detects your framework,
+writes a small managed analytics module + the wiring to load it, and records a
+manifest so it can cleanly uninstall later. It never asks for — or stores — any
+secret.
+
+---
+
+## Quick start
+
+Run it in the root of your web app's repo:
+
+```bash
+# Preview what would change (no files written):
+npx infinite-tag@latest install --ga4-measurement-id G-XXXXXXXXXX
+
+# Apply it (writes the files):
+npx infinite-tag@latest install \
+  --workspace <your-infinite-workspace-id> \
+  --ga4-measurement-id G-XXXXXXXXXX \
+  --posthog-project-key phc_xxxxxxxxxxxxxxxx \
+  --posthog-api-host https://us.i.posthog.com \
+  --yes
+```
+
+> **The easy path:** run `infinite setup` in the Infinite app — once your
+> analytics are connected it prints a ready-to-paste `npx infinite-tag install …`
+> command with your keys and workspace id already filled in. Copy it, run it in
+> your repo, done.
+>
+> **Even easier on the same machine:** `infinite setup` also saves your public
+> keys to `~/.infinite/artifacts/<workspace>.json`, so a bare
+> `npx infinite-tag@latest install` run in your repo discovers them automatically —
+> nothing to paste. Explicit flags or `--artifact-file` always take precedence,
+> and with several saved workspaces you pass `--workspace <id>` to pick one
+> (it never guesses). Only public keys are ever stored in that file.
+
+Without `--yes`, every command is a **dry run** that shows the plan and writes
+nothing. Applying requires `--yes` **and** `--workspace <id>`.
+
+---
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `inspect` | Detect your framework, package manager, and current analytics state. Writes nothing. |
+| `plan` | Show exactly which files would be created/modified, and any blockers. Writes nothing. |
+| `install` | Plan → (with `--yes`) apply → static verification. The main command. |
+| `apply` | Just apply a plan (requires `--yes` and `--workspace`). |
+| `verify` | Static verification of the managed files against the manifest's recorded sha256 hashes; no build is run. |
+| `uninstall` | Remove everything `infinite-tag` installed, restoring your files. Dry run unless `--yes`. |
+| `help` | Usage. |
+
+> Note: the `buildOk` field in `--json` output reflects these static checks
+> only (the name is kept for compatibility); no build is executed.
+
+## Options
+
+| Flag | Description |
+| --- | --- |
+| `--ga4-measurement-id <G-…>` | Public GA4 / gtag measurement ID. |
+| `--posthog-project-key <phc_…>` | Public PostHog project key. |
+| `--posthog-api-host <https://…>` | PostHog ingestion host (e.g. `https://us.i.posthog.com`; reverse-proxy paths are preserved). |
+| `--x-pixel-id <id>` | Public X/Twitter Pixel ID. |
+| `--x-event-tag-id <id>` | X event tag ID (repeatable). |
+| `--artifact-file <path>` | Read the public artifacts above from a JSON file instead of flags. |
+| `--workspace <id>` | Your Infinite workspace id (recorded in the manifest). Required to apply. |
+| `--app-root <path>` | App directory, if it isn't the repo root (monorepos). |
+| `--package-manager <pnpm\|npm\|yarn\|bun>` | Override package-manager detection. |
+| `--yes` | Actually write changes (otherwise dry run). |
+| `--allow-dirty` | Proceed even if the git tree has uncommitted changes. |
+| `--json` | Machine-readable output. |
+
+Only **public** values are ever accepted. Private/server keys (e.g. a PostHog
+*personal* API key) are never passed to this tool.
+
+---
+
+## Supported frameworks
+
+- **Next.js** — App Router and Pages Router
+- **Vite + React**
+- **Static HTML** (a plain `index.html` site)
+
+If your repo can't be confidently classified, `infinite-tag` stops and tells you,
+rather than guessing.
+
+## What it writes to your repo
+
+- A managed analytics module (e.g. `lib/infinite-analytics.ts`) plus the minimal
+  framework wiring to load it. Static-HTML sites get an
+  `<!-- infinite:start --> … <!-- infinite:end -->` block in `index.html`.
+- A manifest at `.infinite/install.json` recording every managed file with a
+  content hash, so `uninstall` can verify and reverse the change.
+
+Every managed file is stamped `// Managed by Infinite` so the tool can recognize
+its own work.
+
+## Uninstall
+
+```bash
+# Preview the removal:
+npx infinite-tag@latest uninstall
+
+# Actually remove it:
+npx infinite-tag@latest uninstall --yes
+```
+
+Uninstall restores your files to their pre-install state byte-for-byte. If you
+hand-edited a managed file, `infinite-tag` refuses to delete it (so your edits are
+never lost) and tells you what to remove manually.
+
+---
+
+## Safety
+
+- **Public keys only.** No secrets are accepted, requested, or stored.
+- **Idempotent.** Running `install` twice does not duplicate the wiring.
+- **Reversible.** `uninstall` cleanly restores your files; applies are written
+  atomically and roll back on failure.
+- **No clobbering.** It refuses to overwrite an existing, unmanaged analytics tag
+  or a file it doesn't recognize as its own.
+- **Stays in your repo.** It never writes outside the app root (no `..`, no
+  absolute paths, no symlink escapes).
+- **Git-aware.** It won't apply or uninstall on a dirty tree unless you pass
+  `--allow-dirty`.
+
+## Community
+
+- Discord: <https://discord.gg/F2CT4C7R>
+- X: [@infiniteOS_](https://x.com/infiniteOS_) — built by [@RiverKhan](https://x.com/RiverKhan)
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/src/apply.d.ts

@@ -0,0 +1,14 @@
+import type { ApplyResult, InstallPlan } from "./types.js";
+export interface ApplyInstallationOptions {
+    root: string;
+    workspaceId: string;
+    plan: InstallPlan;
+    allowDirty?: boolean;
+}
+export declare function applyInstallation(options: ApplyInstallationOptions): ApplyResult;
+export interface FileSnapshot {
+    relativePath: string;
+    contents: string | null;
+}
+export declare function snapshotFiles(root: string, relativePaths: string[]): FileSnapshot[];
+export declare function restoreSnapshot(root: string, snapshot: FileSnapshot[]): void;

package/dist/src/apply.js

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join, relative } from "node:path";
+import { writeFileAtomic } from "./frameworks/shared.js";
+import { getFrameworkAdapter } from "./frameworks/index.js";
+import { computeContentHashes, installManifestRelativePath, writeInstallManifestIfChanged } from "./manifest.js";
+const minimumApplyConfidence = 0.75;
+export function applyInstallation(options) {
+    if (options.plan.blockers.length > 0) {
+        throw new Error(`Refusing to apply an unsupported or blocked plan: ${options.plan.blockers.join(" ")}`);
+    }
+    if (options.plan.confidence < minimumApplyConfidence) {
+        throw new Error(`Refusing to apply a low-confidence plan (${options.plan.confidence.toFixed(2)}).`);
+    }
+    if (options.plan.repoStatus === "dirty" && !options.allowDirty) {
+        throw new Error("Refusing to apply on a dirty git tree without --allow-dirty.");
+    }
+    if (options.plan.applyMode !== "supported") {
+        throw new Error(`Refusing to apply a plan-only framework (${options.plan.framework}). Review the plan instructions and wire it manually for now.`);
+    }
+    const frameworkAdapter = getFrameworkAdapter(options.plan.framework);
+    if (!frameworkAdapter?.apply) {
+        throw new Error(`No apply implementation is registered for ${options.plan.framework}.`);
+    }
+    const snapshot = snapshotFiles(options.root, [
+        ...options.plan.files,
+        installManifestRelativePath
+    ]);
+    try {
+        const frameworkResult = frameworkAdapter.apply({
+            root: options.root,
+            appRoot: options.plan.appRoot,
+            plan: options.plan
+        });
+        const manifest = {
+            workspaceId: options.workspaceId,
+            appRoot: options.plan.appRoot,
+            framework: options.plan.framework,
+            providers: options.plan.providers,
+            files: options.plan.files,
+            envKeys: options.plan.envKeys,
+            contentHashes: computeContentHashes(options.root, options.plan.files),
+            wiringVersion: 1,
+            verifiedAt: null
+        };
+        const manifestWrite = writeInstallManifestIfChanged(options.root, manifest);
+        const changedFiles = [...frameworkResult.changedFiles];
+        if (manifestWrite.changed) {
+            changedFiles.push(relative(options.root, manifestWrite.manifestPath) || ".infinite/install.json");
+        }
+        return {
+            changedFiles,
+            manifestPath: manifestWrite.manifestPath,
+            warnings: frameworkResult.warnings
+        };
+    }
+    catch (error) {
+        restoreSnapshot(options.root, snapshot);
+        throw error;
+    }
+}
+export function snapshotFiles(root, relativePaths) {
+    return relativePaths.map((relativePath) => {
+        const absolutePath = join(root, relativePath);
+        return {
+            relativePath,
+            contents: existsSync(absolutePath) ? readFileSync(absolutePath, "utf8") : null
+        };
+    });
+}
+export function restoreSnapshot(root, snapshot) {
+    for (const file of snapshot) {
+        const absolutePath = join(root, file.relativePath);
+        const current = existsSync(absolutePath) ? readFileSync(absolutePath, "utf8") : null;
+        if (current === file.contents) {
+            continue;
+        }
+        if (file.contents === null) {
+            rmSync(absolutePath, { force: true });
+        }
+        else {
+            writeFileAtomic(absolutePath, file.contents);
+        }
+    }
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function runCli(argv?: string[]): Promise<number>;

package/dist/src/cli.js

@@ -0,0 +1,416 @@
+#!/usr/bin/env node
+import { createInterface } from "node:readline";
+import { resolve } from "node:path";
+import { applyInstallation } from "./apply.js";
+import { isSupportedFramework } from "./frameworks/index.js";
+import { inspectWorkspace } from "./inspect.js";
+import { buildPackageManagerCommands } from "./package-manager.js";
+import { planInstallation } from "./plan.js";
+import { renderApplied, renderBlocked, renderInspect, renderNoArtifacts, renderPreview, renderUninstall, renderUnsupported, renderVerify } from "./render.js";
+import { uninstallInstallation } from "./uninstall.js";
+import { defaultArtifactsDir, discoverWorkspaceArtifacts, resolveWorkspaceArtifacts } from "./workspace-artifacts.js";
+import { verifyInstallation } from "./verify.js";
+const NO_ARTIFACTS_BLOCKER = "No supported public install artifacts were provided.";
+function parsePackageManager(value) {
+    if (value === "pnpm" || value === "npm" || value === "yarn" || value === "bun") {
+        return value;
+    }
+    throw new Error(`Unsupported package manager override: ${value}`);
+}
+function requireValue(flag, value) {
+    if (value === undefined || value.startsWith("--")) {
+        throw new Error(`Missing value for ${flag}.${value !== undefined ? ` (got "${value}" — values beginning with -- are treated as a missing value)` : ""}`);
+    }
+    return value;
+}
+function parseArgs(argv) {
+    const parsed = {
+        command: argv[0] ?? "help",
+        json: false,
+        yes: false,
+        allowDirty: false,
+        xEventTagIds: []
+    };
+    for (let index = 1; index < argv.length; index += 1) {
+        const token = argv[index];
+        const next = argv[index + 1];
+        switch (token) {
+            case "--root":
+                parsed.root = requireValue(token, next);
+                index += 1;
+                break;
+            case "--workspace":
+                parsed.workspaceId = requireValue(token, next);
+                index += 1;
+                break;
+            case "--app-root":
+                parsed.appRoot = requireValue(token, next);
+                index += 1;
+                break;
+            case "--artifact-file":
+                parsed.artifactFile = requireValue(token, next);
+                index += 1;
+                break;
+            case "--ga4-measurement-id":
+                parsed.ga4MeasurementId = requireValue(token, next);
+                index += 1;
+                break;
+            case "--posthog-project-key":
+                parsed.posthogProjectKey = requireValue(token, next);
+                index += 1;
+                break;
+            case "--posthog-api-host":
+                parsed.posthogApiHost = requireValue(token, next);
+                index += 1;
+                break;
+            case "--x-pixel-id":
+                parsed.xPixelId = requireValue(token, next);
+                index += 1;
+                break;
+            case "--x-event-tag-id":
+                parsed.xEventTagIds.push(requireValue(token, next));
+                index += 1;
+                break;
+            case "--package-manager":
+                parsed.packageManager = parsePackageManager(requireValue(token, next));
+                index += 1;
+                break;
+            case "--json":
+                parsed.json = true;
+                break;
+            case "--yes":
+                parsed.yes = true;
+                break;
+            case "--allow-dirty":
+                parsed.allowDirty = true;
+                break;
+            default:
+                throw new Error(`Unknown argument: ${token}. Run infinite-tag help for usage.`);
+        }
+    }
+    return parsed;
+}
+function printResult(_parsed, value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+function printHelp() {
+    console.log([
+        "Usage: infinite-tag <inspect|plan|apply|verify|install|uninstall> [options]",
+        "",
+        "Commands:",
+        "  inspect       Detect framework, app root, package manager, and existing providers",
+        "  plan          Produce a deterministic install plan from public provider artifacts",
+        "  apply         Apply the plan to your repo and record .infinite/install.json",
+        "  verify        Verify managed analytics files match the recorded manifest",
+        "  install       Inspect -> plan -> (confirm) -> apply -> verify",
+        "  uninstall     Remove the managed install recorded in .infinite/install.json",
+        "                (dry run without --yes; destructive with --yes)",
+        "",
+        "Common flags:",
+        "  --root <path>",
+        "  --yes             Apply without the interactive confirmation",
+        "  --allow-dirty     Skip the clean-git-tree safety gate",
+        "  --json            Output machine-readable JSON instead of human text",
+        "",
+        "Artifact flags:",
+        "  --ga4-measurement-id <id>",
+        "  --posthog-project-key <key>",
+        "  --posthog-api-host <host>",
+        "  --x-pixel-id <id>",
+        "  --x-event-tag-id <id>  (repeatable)",
+        "  --artifact-file <path>",
+        "",
+        "When no artifact flags and no --artifact-file are given, plan/apply/install",
+        "auto-discover the file `infinite setup` saved under ~/.infinite/artifacts/",
+        "(<workspace>.json with --workspace; a single saved file otherwise, adopting",
+        "its workspace id). Explicit flags always win."
+    ].join("\n"));
+}
+function detectedManagerFromInspect(packageManager) {
+    if (packageManager === "pnpm" ||
+        packageManager === "npm" ||
+        packageManager === "yarn" ||
+        packageManager === "bun") {
+        return packageManager;
+    }
+    return undefined;
+}
+function maybePrintCommands(command, packageManager, workspaceId) {
+    const resolved = detectedManagerFromInspect(packageManager);
+    if (!resolved || !workspaceId) {
+        return;
+    }
+    const commands = buildPackageManagerCommands(resolved, {
+        pinnedVersion: "0.1.1",
+        workspaceId
+    });
+    if (command === "inspect" || command === "verify") {
+        return;
+    }
+    console.error(`Suggested one-off command: ${commands.oneOff}`);
+}
+/** Classifies why a plan can't be applied, so human mode can show the right guidance. */
+function planIssue(plan) {
+    if (!isSupportedFramework(plan.framework)) {
+        return "unsupported";
+    }
+    if (plan.blockers.includes(NO_ARTIFACTS_BLOCKER)) {
+        return "no-artifacts";
+    }
+    if (plan.blockers.length > 0) {
+        return "blocked";
+    }
+    return null;
+}
+/** Renders the appropriate "can't install" message for human mode; null when the plan is clean. */
+function renderPlanIssue(plan) {
+    switch (planIssue(plan)) {
+        case "unsupported":
+            return renderUnsupported(plan);
+        case "no-artifacts":
+            return renderNoArtifacts(defaultArtifactsDir());
+        case "blocked":
+            return renderBlocked(plan);
+        default:
+            return null;
+    }
+}
+/** Interactive [Y/n] confirmation on stderr, defaulting to yes. Only call in a TTY. */
+async function confirmApply() {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await new Promise((resolveAnswer) => {
+            rl.question("Apply these changes? [Y/n] ", resolveAnswer);
+        });
+        const normalized = answer.trim().toLowerCase();
+        return normalized === "" || normalized === "y" || normalized === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Applies + verifies, then prints the human narration/success block. Returns the exit code. */
+function applyAndRenderHuman(ctx) {
+    if (ctx.plan.repoStatus === "dirty" && !ctx.allowDirty) {
+        console.log("\nYour git tree has uncommitted changes. Commit or stash them first so you can review" +
+            "\nexactly what Infinite adds — or re-run with --allow-dirty to proceed anyway.\n");
+        return 1;
+    }
+    const applyResult = applyInstallation({
+        root: ctx.root,
+        workspaceId: ctx.plan.workspaceId,
+        plan: ctx.plan,
+        allowDirty: ctx.allowDirty
+    });
+    const verifyResult = verifyInstallation({ root: ctx.root });
+    console.log(renderApplied({ inspect: ctx.inspect, plan: ctx.plan, apply: applyResult, verify: verifyResult }));
+    return verifyResult.buildOk ? 0 : 1;
+}
+export async function runCli(argv = process.argv.slice(2)) {
+    try {
+        const parsed = parseArgs(argv);
+        if (parsed.command === "help" || parsed.command === "--help" || parsed.command === "-h") {
+            printHelp();
+            return 0;
+        }
+        const root = resolve(parsed.root ?? process.cwd());
+        if (parsed.command === "uninstall") {
+            const result = uninstallInstallation({
+                root,
+                allowDirty: parsed.allowDirty,
+                dryRun: !parsed.yes
+            });
+            if (parsed.json) {
+                printResult(parsed, result);
+            }
+            else {
+                console.log(renderUninstall(result, !parsed.yes));
+            }
+            if (!parsed.yes) {
+                console.error("Dry run only. Re-run uninstall with --yes to remove the managed install.");
+            }
+            return 0;
+        }
+        const inspect = inspectWorkspace(root, {
+            appRoot: parsed.appRoot,
+            packageManager: parsed.packageManager
+        });
+        let artifacts = resolveWorkspaceArtifacts(root, {
+            artifactFile: parsed.artifactFile,
+            ga4MeasurementId: parsed.ga4MeasurementId,
+            posthogProjectKey: parsed.posthogProjectKey,
+            posthogApiHost: parsed.posthogApiHost,
+            xPixelId: parsed.xPixelId,
+            xEventTagIds: parsed.xEventTagIds
+        });
+        // Same-machine flag-free install: with no artifact flags and no --artifact-file,
+        // fall back to the public artifacts `infinite setup` saved on this machine.
+        // Explicit artifact input always wins, and a workspace id adopted from the
+        // discovered file satisfies the `install --yes` workspace requirement.
+        const hasExplicitArtifacts = parsed.artifactFile !== undefined ||
+            parsed.ga4MeasurementId !== undefined ||
+            parsed.posthogProjectKey !== undefined ||
+            parsed.posthogApiHost !== undefined ||
+            parsed.xPixelId !== undefined ||
+            parsed.xEventTagIds.length > 0;
+        const commandUsesArtifacts = parsed.command === "plan" || parsed.command === "apply" || parsed.command === "install";
+        if (commandUsesArtifacts && !hasExplicitArtifacts) {
+            const discovered = discoverWorkspaceArtifacts({
+                workspaceId: parsed.workspaceId,
+                warn: (message) => console.error(message)
+            });
+            if (discovered) {
+                artifacts = discovered.artifacts;
+                const adoptedWorkspaceId = parsed.workspaceId === undefined ? discovered.workspaceId : undefined;
+                if (adoptedWorkspaceId !== undefined) {
+                    parsed.workspaceId = adoptedWorkspaceId;
+                }
+                console.error(`Discovered saved public artifacts: ${discovered.filePath} (providers: ${discovered.providers.join(", ")}${adoptedWorkspaceId !== undefined ? `; workspace: ${adoptedWorkspaceId}` : ""})`);
+            }
+        }
+        switch (parsed.command) {
+            case "inspect":
+                if (parsed.json) {
+                    printResult(parsed, inspect);
+                }
+                else {
+                    console.log(renderInspect(inspect));
+                }
+                return 0;
+            case "plan": {
+                const plan = planInstallation({
+                    root,
+                    inspect,
+                    workspaceId: parsed.workspaceId,
+                    packageManager: parsed.packageManager,
+                    artifacts
+                });
+                if (parsed.json) {
+                    printResult(parsed, plan);
+                    maybePrintCommands(parsed.command, inspect.packageManager, parsed.workspaceId);
+                    return plan.blockers.length === 0 ? 0 : 1;
+                }
+                const issue = renderPlanIssue(plan);
+                if (issue) {
+                    console.log(issue);
+                    return plan.blockers.length === 0 ? 0 : 1;
+                }
+                console.log(renderPreview(plan));
+                console.log("This was a preview — nothing changed. To apply:  npx infinite-tag install --yes\n");
+                return 0;
+            }
+            case "apply": {
+                if (!parsed.yes) {
+                    throw new Error("Founder approval is required. Re-run apply with --yes to continue.");
+                }
+                if (!parsed.workspaceId) {
+                    throw new Error("apply requires --workspace <workspace-id>.");
+                }
+                const plan = planInstallation({
+                    root,
+                    inspect,
+                    workspaceId: parsed.workspaceId,
+                    packageManager: parsed.packageManager,
+                    artifacts
+                });
+                if (parsed.json) {
+                    const result = applyInstallation({
+                        root,
+                        workspaceId: parsed.workspaceId,
+                        plan,
+                        allowDirty: parsed.allowDirty
+                    });
+                    printResult(parsed, result);
+                    return 0;
+                }
+                const issue = renderPlanIssue(plan);
+                if (issue) {
+                    console.log(issue);
+                    return 1;
+                }
+                return applyAndRenderHuman({ root, inspect, plan, allowDirty: parsed.allowDirty });
+            }
+            case "verify": {
+                const result = verifyInstallation({ root });
+                if (parsed.json) {
+                    printResult(parsed, result);
+                }
+                else {
+                    console.log(renderVerify(result));
+                }
+                return result.buildOk ? 0 : 1;
+            }
+            case "install": {
+                const plan = planInstallation({
+                    root,
+                    inspect,
+                    workspaceId: parsed.workspaceId,
+                    packageManager: parsed.packageManager,
+                    artifacts
+                });
+                // Machine mode: preserve the exact legacy JSON contract.
+                if (parsed.json) {
+                    if (!parsed.yes) {
+                        printResult(parsed, plan);
+                        console.error("Approval required before apply. Re-run with --yes to continue.");
+                        maybePrintCommands(parsed.command, inspect.packageManager, parsed.workspaceId);
+                        return plan.blockers.length === 0 ? 0 : 1;
+                    }
+                    if (!parsed.workspaceId) {
+                        throw new Error("install requires --workspace <workspace-id> when --yes is used.");
+                    }
+                    const applyResult = applyInstallation({
+                        root,
+                        workspaceId: parsed.workspaceId,
+                        plan,
+                        allowDirty: parsed.allowDirty
+                    });
+                    const verifyResult = verifyInstallation({ root });
+                    printResult(parsed, { inspect, plan, apply: applyResult, verify: verifyResult });
+                    return verifyResult.buildOk ? 0 : 1;
+                }
+                // Human mode.
+                const issue = renderPlanIssue(plan);
+                if (issue) {
+                    console.log(issue);
+                    return plan.blockers.length === 0 ? 0 : 1;
+                }
+                if (parsed.yes) {
+                    if (!parsed.workspaceId) {
+                        throw new Error("install requires --workspace <workspace-id> when --yes is used.");
+                    }
+                    return applyAndRenderHuman({ root, inspect, plan, allowDirty: parsed.allowDirty });
+                }
+                // Preview, then either confirm interactively (TTY) or print how to apply.
+                console.log(renderPreview(plan));
+                const canApplyNow = Boolean(parsed.workspaceId);
+                if (process.stdin.isTTY && canApplyNow) {
+                    const approved = await confirmApply();
+                    if (!approved) {
+                        console.log("\nNo changes made. Run it later with:  npx infinite-tag install --yes\n");
+                        return 0;
+                    }
+                    return applyAndRenderHuman({ root, inspect, plan, allowDirty: parsed.allowDirty });
+                }
+                const applyCommand = canApplyNow
+                    ? "npx infinite-tag install --yes"
+                    : "npx infinite-tag install --workspace <your-workspace-id> --yes";
+                console.log(`This was a preview — nothing changed. To apply:  ${applyCommand}\n`);
+                return 0;
+            }
+            default:
+                throw new Error(`Unknown command: ${parsed.command}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        return 1;
+    }
+}
+const invokedAsScript = process.argv[1] && import.meta.url.endsWith(process.argv[1]);
+if (invokedAsScript) {
+    void runCli().then((exitCode) => {
+        process.exitCode = exitCode;
+    });
+}

package/dist/src/frameworks/index.d.ts

@@ -0,0 +1,4 @@
+import type { FrameworkAdapter, SupportedFramework } from "../types.js";
+export declare const frameworkAdapters: FrameworkAdapter[];
+export declare function getFrameworkAdapter(framework: string): FrameworkAdapter | undefined;
+export declare function isSupportedFramework(framework: string): framework is SupportedFramework;