@sparkletree/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SparkleTree
+
+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,68 @@
+# @sparkletree/cli
+
+`sparkletree add` — copy SparkleTree component source into your repo, in the
+shadcn/ui style. No install needed:
+
+```bash
+npx @sparkletree/cli add hero cta
+```
+
+## Commands
+
+```
+sparkletree add <component...> [options]
+sparkletree list
+sparkletree help
+```
+
+| Option | |
+|---|---|
+| `--dir <path>` | Where components are written. Default `components`. |
+| `--cwd <path>` | Project root. Default: current directory. |
+| `--force` | Overwrite files that already exist. |
+| `--dry-run` | Show what would happen; write nothing. |
+
+Dependencies are resolved for you — asking for `hero` also writes `provider` if
+you do not have it.
+
+## Components
+
+| | |
+|---|---|
+| `provider` | The `SparkletreeProvider` wrapper, reading your env vars. |
+| `hero` | Streaming hero: headline, body, art. |
+| `cta` | Streaming call-to-action. |
+| `copy-card` | The copy-card creative. |
+| `product-card` | Product creative with price and CTA. |
+
+The copies require Tailwind CSS for their default classes. Swap them freely —
+they are yours.
+
+## What "yours" means, and the one thing it does not include
+
+Copied components are your code: we cannot patch them, deprecate them, or know
+what they look like a year from now. So they are **wire-ignorant by
+construction** — no event names, no protocol versions, no transports, no
+endpoints, no timing constants. A CI test enforces this per component.
+
+Everything that speaks the wire stays in
+[`@sparkletree/react`](https://www.npmjs.com/package/@sparkletree/react) and
+[`@sparkletree/core`](https://www.npmjs.com/package/@sparkletree/core), which
+the copies import from. That is what buys the property that makes copy-paste
+distribution safe: **a protocol change is a version bump, never a migration
+guide.**
+
+It also means the adaptation mark is not in the copied source. It renders
+inside `StreamText`, in npm, and deleting it from your copy is not possible
+because it was never there. That is deliberate — see rule 4 in the
+[SDK README](https://gitlab.com/sparkletree/sparkletree-sdk/-/blob/main/README.md).
+
+## Choose one distribution, not both
+
+Either import components from `@sparkletree/react`, or copy them with this CLI
+and import from `./components/sparkletree/…`. Doing both gives you two Heroes
+with the same name and a confusing diff.
+
+## Requirements
+
+Node >= 18. ESM only.

package/dist/add.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `sparkletree add <component…>`
+ *
+ * Copies component source into the project. Everything about how it behaves
+ * follows from one principle: THIS WRITES TO SOMEONE ELSE'S REPOSITORY.
+ *
+ *   - never overwrite without `--force`. The file may be three months of the
+ *     customer's edits, and "the CLI reverted my hero" is unrecoverable if we
+ *     wrote first and asked later;
+ *   - report the dependencies to install rather than running a package
+ *     manager. Which one, which lockfile, which workspace flag — those are
+ *     theirs to decide, and guessing wrong dirties a lockfile in a PR;
+ *   - `--dry-run` shows exactly what would happen and touches nothing.
+ */
+import { type RegistryComponent } from "./registry.js";
+export interface AddOptions {
+    /** Project root. Defaults to the working directory. */
+    cwd?: string;
+    /** Where components land, relative to cwd. */
+    targetDir?: string;
+    force?: boolean;
+    dryRun?: boolean;
+}
+export interface AddResult {
+    written: string[];
+    skipped: {
+        path: string;
+        reason: string;
+    }[];
+    dependencies: string[];
+    components: RegistryComponent[];
+}
+export declare function add(names: string[], options?: AddOptions): Promise<AddResult>;
+/** Human-readable summary. Mirrors what `add` actually did. */
+export declare function formatAddResult(result: AddResult, dryRun?: boolean): string;
+/** Where `add` would write, for `--help` and for tests. */
+export declare function targetPathFor(component: RegistryComponent, targetDir?: string): string;
+//# sourceMappingURL=add.d.ts.map

package/dist/add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../src/add.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEhF,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5C,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,iBAAiB,EAAE,CAAC;CACjC;AAYD,wBAAsB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,SAAS,CAAC,CAqDvF;AAED,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,UAAQ,GAAG,MAAM,CA6BzE;AAED,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,SAAS,EAAE,iBAAiB,EAAE,SAAS,SAAe,GAAG,MAAM,CAE5F"}

package/dist/add.js

@@ -0,0 +1,100 @@
+/**
+ * `sparkletree add <component…>`
+ *
+ * Copies component source into the project. Everything about how it behaves
+ * follows from one principle: THIS WRITES TO SOMEONE ELSE'S REPOSITORY.
+ *
+ *   - never overwrite without `--force`. The file may be three months of the
+ *     customer's edits, and "the CLI reverted my hero" is unrecoverable if we
+ *     wrote first and asked later;
+ *   - report the dependencies to install rather than running a package
+ *     manager. Which one, which lockfile, which workspace flag — those are
+ *     theirs to decide, and guessing wrong dirties a lockfile in a PR;
+ *   - `--dry-run` shows exactly what would happen and touches nothing.
+ */
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { resolveWithDependencies } from "./registry.js";
+/** What already sits at a path, without reading its contents. */
+async function pathKind(path) {
+    try {
+        const info = await stat(path);
+        return info.isDirectory() ? "directory" : "file";
+    }
+    catch {
+        return null;
+    }
+}
+export async function add(names, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const targetDir = options.targetDir ?? "components";
+    const components = resolveWithDependencies(names);
+    const written = [];
+    const skipped = [];
+    const dependencies = new Set();
+    for (const component of components) {
+        for (const dependency of component.dependencies)
+            dependencies.add(dependency);
+        for (const file of component.files) {
+            const absolute = resolve(cwd, targetDir, file.path);
+            // Refuse to escape the target directory. Registry paths are ours today,
+            // but a path-traversal check on a tool that writes files is not
+            // something to add after it matters. The check is against ".." as a
+            // path segment — a filename that merely STARTS with dots ("..foo.tsx")
+            // is still inside the target and must not trip it.
+            const relativeToTarget = relative(resolve(cwd, targetDir), absolute);
+            if (relativeToTarget.startsWith(".." + sep) || isAbsolute(relativeToTarget)) {
+                throw new Error(`Registry path escapes the target directory: ${file.path}`);
+            }
+            // A directory at the target path is never overwritten, --force or not:
+            // writeFile would die with a raw EISDIR, and recursive removal of a
+            // customer's directory is not this tool's call to make.
+            const existing = await pathKind(absolute);
+            if (existing === "directory") {
+                skipped.push({
+                    path: relative(cwd, absolute),
+                    reason: "a directory exists at this path — remove it or choose another --dir",
+                });
+                continue;
+            }
+            if (!options.force && existing === "file") {
+                skipped.push({
+                    path: relative(cwd, absolute),
+                    reason: "already exists — pass --force to overwrite",
+                });
+                continue;
+            }
+            if (!options.dryRun) {
+                await mkdir(dirname(absolute), { recursive: true });
+                await writeFile(absolute, file.content, "utf8");
+            }
+            written.push(relative(cwd, absolute));
+        }
+    }
+    return { written, skipped, dependencies: [...dependencies], components };
+}
+/** Human-readable summary. Mirrors what `add` actually did. */
+export function formatAddResult(result, dryRun = false) {
+    const lines = [];
+    const verb = dryRun ? "Would write" : "Wrote";
+    if (result.written.length) {
+        lines.push(`${verb}:`);
+        for (const path of result.written)
+            lines.push(`  ${path}`);
+    }
+    if (result.skipped.length) {
+        lines.push("", "Skipped:");
+        for (const item of result.skipped)
+            lines.push(`  ${item.path} — ${item.reason}`);
+    }
+    if (result.dependencies.length) {
+        lines.push("", "Install these if you haven't already:", `  ${result.dependencies.join(" ")}`);
+    }
+    lines.push("", "These files are yours — edit them freely. Streaming, timing and the", "adaptation mark live in @sparkletree/core, so upgrades reach you without", "re-copying anything.", "", "The default classNames assume Tailwind CSS — swap them freely if you", "style with something else.");
+    return lines.join("\n");
+}
+/** Where `add` would write, for `--help` and for tests. */
+export function targetPathFor(component, targetDir = "components") {
+    return join(targetDir, component.files[0].path);
+}
+//# sourceMappingURL=add.js.map

package/dist/add.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.js","sourceRoot":"","sources":["../src/add.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAE9E,OAAO,EAAE,uBAAuB,EAA0B,MAAM,eAAe,CAAC;AAkBhF,iEAAiE;AACjE,KAAK,UAAU,QAAQ,CAAC,IAAY;IAClC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9B,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,KAAe,EAAE,UAAsB,EAAE;IACjE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACzC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,YAAY,CAAC;IACpD,MAAM,UAAU,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;IAElD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAuC,EAAE,CAAC;IACvD,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IAEvC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,KAAK,MAAM,UAAU,IAAI,SAAS,CAAC,YAAY;YAAE,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAE9E,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,KAAK,EAAE,CAAC;YACnC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;YAEpD,wEAAwE;YACxE,gEAAgE;YAChE,oEAAoE;YACpE,uEAAuE;YACvE,mDAAmD;YACnD,MAAM,gBAAgB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,QAAQ,CAAC,CAAC;YACrE,IAAI,gBAAgB,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC;gBAC5E,MAAM,IAAI,KAAK,CAAC,+CAA+C,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YAC9E,CAAC;YAED,uEAAuE;YACvE,oEAAoE;YACpE,wDAAwD;YACxD,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC1C,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;gBAC7B,OAAO,CAAC,IAAI,CAAC;oBACX,IAAI,EAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;oBAC7B,MAAM,EAAE,qEAAqE;iBAC9E,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YACD,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;gBAC1C,OAAO,CAAC,IAAI,CAAC;oBACX,IAAI,EAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;oBAC7B,MAAM,EAAE,4CAA4C;iBACrD,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;gBACpB,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;gBACpD,MAAM,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAClD,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,GAAG,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC;AAC3E,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,eAAe,CAAC,MAAiB,EAAE,MAAM,GAAG,KAAK;IAC/D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC;IAE9C,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;QACvB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;QAC3B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CACR,EAAE,EACF,uCAAuC,EACvC,KAAK,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CACrC,CAAC;IACJ,CAAC;IACD,KAAK,CAAC,IAAI,CACR,EAAE,EACF,qEAAqE,EACrE,0EAA0E,EAC1E,sBAAsB,EACtB,EAAE,EACF,sEAAsE,EACtE,4BAA4B,CAC7B,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,aAAa,CAAC,SAA4B,EAAE,SAAS,GAAG,YAAY;IAClF,OAAO,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAClD,CAAC"}

package/dist/bin.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * The `sparkletree` binary.
+ *
+ * Argument parsing by hand rather than a dependency: this CLI has three
+ * commands and a handful of flags, and a customer running `npx @sparkletree/cli
+ * add hero` should not be installing a parser to do it.
+ */
+interface ParsedArgs {
+    command: string;
+    names: string[];
+    dir?: string;
+    cwd?: string;
+    force: boolean;
+    dryRun: boolean;
+    help: boolean;
+    version: boolean;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+declare function main(argv: string[]): Promise<number>;
+export { main };
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;GAMG;AA6BH,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB;AAeD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAuBpD;AAaD,iBAAe,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAuEnD;AA6CD,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/dist/bin.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * The `sparkletree` binary.
+ *
+ * Argument parsing by hand rather than a dependency: this CLI has three
+ * commands and a handful of flags, and a customer running `npx @sparkletree/cli
+ * add hero` should not be installing a parser to do it.
+ */
+import { realpathSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { add, formatAddResult } from "./add.js";
+import { REGISTRY, findComponent } from "./registry.js";
+const HELP = `sparkletree — add SparkleTree components to your project
+
+Usage
+  sparkletree add <component...> [options]
+  sparkletree list
+  sparkletree help
+
+Options
+  --dir <path>    where components are written (default: components)
+  --cwd <path>    project root (default: current directory)
+  --force         overwrite files that already exist
+  --dry-run       show what would happen; write nothing
+  -h, --help      show this help
+  --version       show the CLI version
+
+Examples
+  npx @sparkletree/cli add hero cta
+  npx @sparkletree/cli add product-card --dir src/components
+`;
+/**
+ * The value after a value-taking flag. `--dir --force` must fail loudly, not
+ * write into a directory literally named "--force"; a trailing `--dir` must
+ * fail loudly, not become `undefined` and silently mean the default.
+ */
+function optionValue(flag, rest, index) {
+    const value = rest[index];
+    if (value === undefined || value.startsWith("--")) {
+        throw new Error(`Option ${flag} needs a value, got ${value ?? "end of arguments"}`);
+    }
+    return value;
+}
+export function parseArgs(argv) {
+    const [command = "help", ...rest] = argv;
+    const parsed = {
+        command,
+        names: [],
+        force: false,
+        dryRun: false,
+        help: false,
+        version: false,
+    };
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        if (arg === "--force")
+            parsed.force = true;
+        else if (arg === "--dry-run")
+            parsed.dryRun = true;
+        else if (arg === "--help" || arg === "-h")
+            parsed.help = true;
+        else if (arg === "--version")
+            parsed.version = true;
+        else if (arg === "--dir")
+            parsed.dir = optionValue("--dir", rest, ++index);
+        else if (arg === "--cwd")
+            parsed.cwd = optionValue("--cwd", rest, ++index);
+        else if (arg.startsWith("--"))
+            throw new Error(`Unknown option ${arg}`);
+        else
+            parsed.names.push(arg);
+    }
+    return parsed;
+}
+/** The CLI's own version, read from the package.json the build ships next to. */
+function cliVersion() {
+    try {
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+async function main(argv) {
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        console.error("\n" + HELP);
+        return 1;
+    }
+    // --help and --version work from any position: `sparkletree add --help`
+    // shows usage rather than dying on an "unknown option".
+    if (args.help) {
+        console.log(HELP);
+        return 0;
+    }
+    if (args.version) {
+        console.log(cliVersion());
+        return 0;
+    }
+    switch (args.command) {
+        case "list": {
+            console.log("Available components:\n");
+            for (const component of REGISTRY) {
+                console.log(`  ${component.name.padEnd(14)} ${component.description}`);
+            }
+            return 0;
+        }
+        case "add": {
+            if (!args.names.length) {
+                console.error("Which component? Try `sparkletree list`.\n");
+                console.error(HELP);
+                return 1;
+            }
+            const unknown = args.names.filter((name) => !findComponent(name));
+            if (unknown.length) {
+                console.error(`Unknown component(s): ${unknown.join(", ")}`);
+                console.error(`Available: ${REGISTRY.map((c) => c.name).join(", ")}`);
+                return 1;
+            }
+            const result = await add(args.names, {
+                cwd: args.cwd,
+                targetDir: args.dir,
+                force: args.force,
+                dryRun: args.dryRun,
+            });
+            console.log(formatAddResult(result, args.dryRun));
+            // Skipped files are not a failure: re-running `add` on a project that
+            // already has the component is a normal thing to do, and exiting
+            // non-zero would break it in CI for no reason.
+            return 0;
+        }
+        case "help":
+        case "--help":
+        case "-h":
+            console.log(HELP);
+            return 0;
+        case "--version":
+            console.log(cliVersion());
+            return 0;
+        default:
+            console.error(`Unknown command "${args.command}"\n`);
+            console.error(HELP);
+            return 1;
+    }
+}
+/**
+ * Are we the entry point, or is something importing us?
+ *
+ * Importing this module (tests, programmatic use) must not run a command or
+ * call process.exit — but the check has to survive how package managers
+ * actually install a `bin`.
+ *
+ * npm installs it as a bare SYMLINK: `node_modules/.bin/sparkletree` →
+ * `dist/bin.js`. Node then resolves `import.meta.url` through the symlink to
+ * the real file while leaving `process.argv[1]` as the symlink path. Comparing
+ * the two textually — which this used to do, against argv[1]'s basename —
+ * asks whether "…/dist/bin.js" ends with "sparkletree". It does not, so
+ * `npx sparkletree` parsed nothing, printed nothing, and exited 0. A silent
+ * no-op on the one command every consumer runs first.
+ *
+ * (pnpm masked it: pnpm writes a shell shim that execs the real path, so
+ * argv[1] and import.meta.url already agree. So do all our own tests, which
+ * import this module rather than spawning the installed binary.)
+ *
+ * realpath both sides and compare. Symlink, shim or direct — they agree.
+ */
+function isEntryPoint() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        // A deleted or unreadable argv[1] is not us.
+        return false;
+    }
+}
+if (isEntryPoint()) {
+    main(process.argv.slice(2))
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    });
+}
+export { main };
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @sparkletree/cli — programmatic surface.
+ *
+ * The binary is a thin wrapper over these. Exported so the parity harness and
+ * anyone scripting a scaffold can use `add` without shelling out.
+ */
+export { add, formatAddResult, targetPathFor, type AddOptions, type AddResult } from "./add.js";
+export { REGISTRY, findComponent, resolveWithDependencies, type RegistryComponent, } from "./registry.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,GAAG,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAChG,OAAO,EACL,QAAQ,EACR,aAAa,EACb,uBAAuB,EACvB,KAAK,iBAAiB,GACvB,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @sparkletree/cli — programmatic surface.
+ *
+ * The binary is a thin wrapper over these. Exported so the parity harness and
+ * anyone scripting a scaffold can use `add` without shelling out.
+ */
+export { add, formatAddResult, targetPathFor } from "./add.js";
+export { REGISTRY, findComponent, resolveWithDependencies, } from "./registry.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,GAAG,EAAE,eAAe,EAAE,aAAa,EAAmC,MAAM,UAAU,CAAC;AAChG,OAAO,EACL,QAAQ,EACR,aAAa,EACb,uBAAuB,GAExB,MAAM,eAAe,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The component registry.
+ *
+ * `sparkletree add hero` copies source into the customer's repo, shadcn-style.
+ * Those copies are theirs: we cannot patch them, cannot deprecate them, and
+ * cannot assume anything about what they have become by the time we ship the
+ * next protocol version.
+ *
+ * Which is the whole reason for the rule enforced in `registry.test.ts`:
+ *
+ *   COPIES ARE WIRE-IGNORANT. ONLY NPM SPEAKS THE WIRE.
+ *
+ * A copied component may import from `@sparkletree/react` and
+ * `@sparkletree/core`. It may not contain an event name, a protocol version,
+ * a timing constant, or a URL. The moment one does, a protocol change stops
+ * being a version bump and becomes a migration guide addressed to every
+ * customer who ever ran `add` — and they will not all read it.
+ *
+ * The registry ships as data, not as files fetched at install time: a CLI that
+ * pulls source off the network at `add` time is a supply-chain hole in every
+ * customer's build.
+ */
+export interface RegistryComponent {
+    name: string;
+    description: string;
+    /** Files written, relative to the target directory. */
+    files: {
+        path: string;
+        content: string;
+    }[];
+    /** npm packages the copy needs. */
+    dependencies: string[];
+    /** Other registry components this one requires. */
+    registryDependencies: string[];
+}
+export declare const REGISTRY: readonly RegistryComponent[];
+export declare function findComponent(name: string): RegistryComponent | undefined;
+/**
+ * Resolve a component plus everything it needs, dependencies first.
+ *
+ * Depth-first with a visited set, so a diamond in the graph copies each file
+ * once and a cycle terminates rather than recursing until the stack gives out.
+ */
+export declare function resolveWithDependencies(names: string[]): RegistryComponent[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C,mCAAmC;IACnC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mDAAmD;IACnD,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AAsWD,eAAO,MAAM,QAAQ,EAAE,SAAS,iBAAiB,EAoChD,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,iBAAiB,EAAE,CAe5E"}

package/dist/registry.js

@@ -0,0 +1,438 @@
+/**
+ * The component registry.
+ *
+ * `sparkletree add hero` copies source into the customer's repo, shadcn-style.
+ * Those copies are theirs: we cannot patch them, cannot deprecate them, and
+ * cannot assume anything about what they have become by the time we ship the
+ * next protocol version.
+ *
+ * Which is the whole reason for the rule enforced in `registry.test.ts`:
+ *
+ *   COPIES ARE WIRE-IGNORANT. ONLY NPM SPEAKS THE WIRE.
+ *
+ * A copied component may import from `@sparkletree/react` and
+ * `@sparkletree/core`. It may not contain an event name, a protocol version,
+ * a timing constant, or a URL. The moment one does, a protocol change stops
+ * being a version bump and becomes a migration guide addressed to every
+ * customer who ever ran `add` — and they will not all read it.
+ *
+ * The registry ships as data, not as files fetched at install time: a CLI that
+ * pulls source off the network at `add` time is a supply-chain hole in every
+ * customer's build.
+ */
+const HERO_TSX = `"use client";
+
+import { StreamText, useIsland, type UseIslandOptions } from "@sparkletree/react";
+import { themeStyle } from "@sparkletree/core";
+
+/**
+ * Your hero. Edit freely — this file is yours.
+ *
+ * What you should NOT need to touch, and what you will not find here: when the
+ * copy paints, how long it holds, whether it types or lands composed, and
+ * whether it carries the adaptation mark. All of that lives in
+ * @sparkletree/core and @sparkletree/react so it can be fixed for you without
+ * you re-copying this file.
+ *
+ * \`fallback\` is required. There is no loading state and no skeleton: if the
+ * network is slow or the campaign is unreachable, this copy is what your
+ * visitor reads. Write it as if it were the only version — often it is.
+ *
+ * Requires Tailwind CSS for the default classes — swap them freely.
+ */
+export interface HeroProps {
+  campaignId: string;
+  /** First paint. Real copy, never a placeholder. */
+  fallback: UseIslandOptions["fallback"];
+}
+
+/**
+ * Server-driven URLs are configuration, not trust. Only http(s), mailto and
+ * tel absolutes and relative navigations ("/", "./", "#", "?") pass; anything
+ * else — javascript:, data:, an unprefixed string — is dropped.
+ */
+function safeActionUrl(url: string | null | undefined): string | undefined {
+  if (!url) return undefined;
+  if (
+    (url.startsWith("/") && !url.startsWith("//")) ||
+    url.startsWith("./") ||
+    url.startsWith("#") ||
+    url.startsWith("?")
+  ) {
+    return url;
+  }
+  try {
+    const protocol = new URL(url).protocol;
+    if (["https:", "http:", "mailto:", "tel:"].includes(protocol)) return url;
+  } catch {
+    // Not a parseable URL at all.
+  }
+  return undefined;
+}
+
+export function Hero({ campaignId, fallback }: HeroProps) {
+  const { state, ref } = useIsland({ campaignId, island: "hero", fallback });
+  const backgroundImage = safeActionUrl(state.backgroundImage);
+
+  return (
+    <section
+      ref={ref}
+      className="relative overflow-hidden rounded-2xl p-10"
+      style={themeStyle(state.theme)}
+    >
+      {backgroundImage ? (
+        <img
+          src={backgroundImage}
+          alt=""
+          className="absolute inset-0 h-full w-full object-cover"
+        />
+      ) : null}
+
+      <div className="relative">
+        {state.fields.greeting.text ? (
+          <StreamText
+            field={state.fields.greeting}
+            as="p"
+            className="text-sm uppercase tracking-wide opacity-80"
+          />
+        ) : null}
+
+        {/* h2 to match the packaged Hero. The heading level is yours: pass
+            as="h1" if this section is your page's primary heading. */}
+        <StreamText
+          field={state.fields.headline}
+          as="h2"
+          className="mt-2 text-4xl font-semibold"
+        />
+
+        {state.fields.body.text ? (
+          <StreamText field={state.fields.body} as="p" className="mt-4 max-w-prose" />
+        ) : null}
+      </div>
+    </section>
+  );
+}
+`;
+const CTA_TSX = `"use client";
+
+import { StreamText, useIsland, useSparkletree, type UseIslandOptions } from "@sparkletree/react";
+import { readableTextColor, themeStyle, track } from "@sparkletree/core";
+
+/**
+ * Your call to action. Edit freely.
+ *
+ * The button keeps its size while the label streams in, so the surrounding
+ * layout does not shift under the visitor's cursor mid-click.
+ *
+ * Requires Tailwind CSS for the default classes — swap them freely.
+ */
+export interface CtaProps extends Omit<UseIslandOptions, "island"> {
+  /** Where the button goes when the server has not resolved an action. */
+  href?: string;
+  onClick?: () => void;
+}
+
+/**
+ * Server-driven URLs are configuration, not trust. Only http(s), mailto and
+ * tel absolutes and relative navigations ("/", "./", "#", "?") pass; anything
+ * else — javascript:, data:, an unprefixed string — is dropped.
+ */
+function safeActionUrl(url: string | null | undefined): string | undefined {
+  if (!url) return undefined;
+  if (
+    (url.startsWith("/") && !url.startsWith("//")) ||
+    url.startsWith("./") ||
+    url.startsWith("#") ||
+    url.startsWith("?")
+  ) {
+    return url;
+  }
+  try {
+    const protocol = new URL(url).protocol;
+    if (["https:", "http:", "mailto:", "tel:"].includes(protocol)) return url;
+  } catch {
+    // Not a parseable URL at all.
+  }
+  return undefined;
+}
+
+export function Cta(props: CtaProps) {
+  const { href, onClick, ...islandOptions } = props;
+  const { apiBase, organizationId } = useSparkletree();
+  const { state, ref } = useIsland({ ...islandOptions, island: "cta" });
+  // A rejected server action falls back to the href prop you control. The
+  // prop is vetted too — the same render path, the same rules, one outcome.
+  const action = safeActionUrl(state.ctaAction) ?? safeActionUrl(href);
+  const { campaignId, surfaceId } = islandOptions;
+  const variantId = state.variantId ?? undefined;
+  // A surface-only Cta has no campaignId prop, but the click must still be
+  // attributed: the server names the campaign it served in the terminal
+  // done.meta, mirroring the impression path in useIsland.
+  const metaCampaignId =
+    typeof state.meta?.campaignId === "string" ? state.meta.campaignId : undefined;
+  const resolvedCampaignId = campaignId ?? metaCampaignId;
+
+  // The click is the other half of CTR. The SDK tells the server to suppress
+  // its own counting for this page view — so if nothing here reports the
+  // click, CTR for SDK traffic is a division by silence. Fire-and-forget:
+  // track never throws and never blocks the navigation.
+  const handleClick = () => {
+    if (resolvedCampaignId) {
+      void track(
+        { apiBase, organizationId, campaignId: resolvedCampaignId, variantId, surfaceId },
+        "click",
+        { island: "cta" },
+      );
+    }
+    onClick?.();
+  };
+
+  // Shared by the link and the no-destination fallback below.
+  const shared = {
+    onClick: handleClick,
+    className:
+      "inline-flex min-h-11 min-w-40 items-center justify-center rounded-full px-6 font-medium",
+    style: {
+      ...themeStyle(state.theme),
+      // --st-cta-text is the label ink that reads on the theme's primary, so
+      // a light theme can never produce a ghost button.
+      ...(state.theme?.colors?.primary
+        ? { ["--st-cta-text" as string]: readableTextColor(state.theme.colors.primary) }
+        : {}),
+    },
+    // A CTA whose label is still empty is not yet a button a viewer can
+    // meaningfully act on — but it must still occupy its space, or the
+    // layout shifts when the copy lands.
+    "aria-disabled": state.fields.cta.text ? undefined : true,
+  };
+
+  // Neither the stream nor you resolved a destination: render a
+  // non-interactive element rather than an inert <a> with no href, which
+  // some assistive tech still announces as a link to nowhere. Clicks are
+  // still observed — engagement with the creative counts toward CTR whether
+  // or not it navigates.
+  if (action === undefined) {
+    return (
+      <span ref={ref as unknown as (element: HTMLSpanElement | null) => void} {...shared}>
+        <StreamText field={state.fields.cta} />
+      </span>
+    );
+  }
+
+  return (
+    <a ref={ref} href={action} {...shared}>
+      <StreamText field={state.fields.cta} />
+    </a>
+  );
+}
+`;
+const COPY_CARD_TSX = `import { StreamText, staticField, type ContentSource } from "@sparkletree/react";
+
+/**
+ * A copy card fed by /content rather than a stream.
+ *
+ * \`contentSource\` comes from the /content response's meta. Pass it through —
+ * do not default it to "generated" to get the mark, and do not hardcode
+ * "static" to lose it. The mark follows the copy's provenance, and both
+ * shortcuts make it say something untrue.
+ *
+ * \`staticField\` builds the field object for you. Keep using it rather than
+ * writing the object literal yourself: the field's shape belongs to the npm
+ * package, and the helper is what lets it grow without breaking this file.
+ *
+ * Requires Tailwind CSS for the default classes — swap them freely.
+ */
+export interface CopyCardProps {
+  headline?: string;
+  body?: string;
+  /** Provenance of this copy, from the /content response's meta. */
+  contentSource?: ContentSource;
+}
+
+export function CopyCard({ headline, body, contentSource = "static" }: CopyCardProps) {
+  return (
+    <article className="rounded-xl border p-6">
+      <StreamText
+        field={staticField(headline, contentSource)}
+        as="h3"
+        className="text-lg font-semibold"
+      />
+      {body ? (
+        <StreamText field={staticField(body, contentSource)} as="p" className="mt-2 opacity-80" />
+      ) : null}
+    </article>
+  );
+}
+`;
+const PRODUCT_CARD_TSX = `import { StreamText, staticField, type ContentSource } from "@sparkletree/react";
+
+/**
+ * A product card.
+ *
+ * Note that the name and price are always "static": they come from your
+ * catalogue, not from a model. Only the description can be adapted, so only
+ * the description can carry the mark — marking a price as adapted would be a
+ * straightforward falsehood about the price.
+ *
+ * \`staticField\` builds the field object for you. Keep using it rather than
+ * writing the object literal yourself: the field's shape belongs to the npm
+ * package, and the helper is what lets it grow without breaking this file.
+ *
+ * Requires Tailwind CSS for the default classes — swap them freely.
+ */
+export interface ProductCardProps {
+  product: {
+    name: string;
+    description?: string;
+    price?: string | number;
+    imageUrl?: string;
+  };
+  /** Provenance of the description. The name and price are never generated. */
+  contentSource?: ContentSource;
+}
+
+export function ProductCard({ product, contentSource = "static" }: ProductCardProps) {
+  return (
+    <article className="rounded-xl border p-4">
+      {product.imageUrl ? (
+        <img
+          src={product.imageUrl}
+          alt={product.name}
+          loading="lazy"
+          className="aspect-square w-full rounded-lg object-cover"
+        />
+      ) : null}
+      <StreamText field={staticField(product.name, "static")} as="h3" className="mt-3 font-medium" />
+      {product.description ? (
+        <StreamText
+          field={staticField(product.description, contentSource)}
+          as="p"
+          className="mt-1 text-sm opacity-75"
+        />
+      ) : null}
+      {product.price != null ? <p className="mt-2 font-semibold">{product.price}</p> : null}
+    </article>
+  );
+}
+`;
+const PROVIDER_TSX = `"use client";
+
+import { SparkletreeProvider } from "@sparkletree/react";
+import type { ReactNode } from "react";
+
+/**
+ * Wrap your app once.
+ *
+ * One provider per page view. It holds the org, the API base and the context
+ * snapshot, so every island on the page is adapted to the same moment rather
+ * than to two separate reads of the clock.
+ *
+ * The env checks below throw at module load, on purpose: a missing variable
+ * should fail your build or your first render with its own name in the error,
+ * not ship as a provider quietly pointed at \`undefined\`. The environment is
+ * read through globalThis because not every bundler (Vite, browser) defines
+ * \`process\` — there, the errors below tell you to wire the values yourself.
+ */
+const runtimeProcess = (globalThis as { process?: { env?: Record<string, string | undefined> } })
+  .process;
+const env: Record<string, string | undefined> = runtimeProcess?.env ?? {};
+const envApiBase = env.NEXT_PUBLIC_SPARKLETREE_API_BASE;
+const envOrganizationId = env.NEXT_PUBLIC_SPARKLETREE_ORG_ID;
+
+if (!envApiBase) {
+  throw new Error(
+    runtimeProcess
+      ? "SparkleTree: Set NEXT_PUBLIC_SPARKLETREE_API_BASE (for example in .env.local) " +
+          "to your SparkleTree API origin."
+      : "SparkleTree: this environment has no process global (Vite, browser, ...). " +
+          "Expose your SparkleTree API origin to the bundle (for example via import.meta.env) " +
+          "and assign it to apiBase below.",
+  );
+}
+if (!envOrganizationId) {
+  throw new Error(
+    runtimeProcess
+      ? "SparkleTree: Set NEXT_PUBLIC_SPARKLETREE_ORG_ID (for example in .env.local) " +
+          "to your SparkleTree organization id."
+      : "SparkleTree: this environment has no process global (Vite, browser, ...). " +
+          "Expose your SparkleTree organization id to the bundle (for example via import.meta.env) " +
+          "and assign it to organizationId below.",
+  );
+}
+
+const apiBase: string = envApiBase;
+const organizationId: string = envOrganizationId;
+
+export function SparkleTree({ children }: { children: ReactNode }) {
+  return (
+    <SparkletreeProvider apiBase={apiBase} organizationId={organizationId}>
+      {children}
+    </SparkletreeProvider>
+  );
+}
+`;
+export const REGISTRY = [
+    {
+        name: "provider",
+        description: "The page-level provider. Every other component needs it.",
+        files: [{ path: "sparkletree/provider.tsx", content: PROVIDER_TSX }],
+        dependencies: ["@sparkletree/react", "@sparkletree/core"],
+        registryDependencies: [],
+    },
+    {
+        name: "hero",
+        description: "Streaming hero: greeting, headline, body, adaptive art.",
+        files: [{ path: "sparkletree/hero.tsx", content: HERO_TSX }],
+        dependencies: ["@sparkletree/react", "@sparkletree/core"],
+        registryDependencies: ["provider"],
+    },
+    {
+        name: "cta",
+        description: "Streaming call to action with a stable hit area.",
+        files: [{ path: "sparkletree/cta.tsx", content: CTA_TSX }],
+        dependencies: ["@sparkletree/react", "@sparkletree/core"],
+        registryDependencies: ["provider"],
+    },
+    {
+        name: "copy-card",
+        description: "Content-fed copy card.",
+        files: [{ path: "sparkletree/copy-card.tsx", content: COPY_CARD_TSX }],
+        dependencies: ["@sparkletree/react"],
+        registryDependencies: ["provider"],
+    },
+    {
+        name: "product-card",
+        description: "Content-fed product card.",
+        files: [{ path: "sparkletree/product-card.tsx", content: PRODUCT_CARD_TSX }],
+        dependencies: ["@sparkletree/react"],
+        registryDependencies: ["provider"],
+    },
+];
+export function findComponent(name) {
+    return REGISTRY.find((component) => component.name === name);
+}
+/**
+ * Resolve a component plus everything it needs, dependencies first.
+ *
+ * Depth-first with a visited set, so a diamond in the graph copies each file
+ * once and a cycle terminates rather than recursing until the stack gives out.
+ */
+export function resolveWithDependencies(names) {
+    const resolved = [];
+    const seen = new Set();
+    const visit = (name) => {
+        if (seen.has(name))
+            return;
+        seen.add(name);
+        const component = findComponent(name);
+        if (!component)
+            throw new Error(`Unknown component "${name}"`);
+        for (const dependency of component.registryDependencies)
+            visit(dependency);
+        resolved.push(component);
+    };
+    for (const name of names)
+        visit(name);
+    return resolved;
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@sparkletree/cli",
+  "version": "0.1.0",
+  "description": "sparkletree — add SparkleTree components to your project.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "sparkletree": "./dist/bin.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.19.11",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/sparkletree/sparkletree-sdk.git",
+    "directory": "cli"
+  },
+  "author": "SparkleTree",
+  "homepage": "https://gitlab.com/sparkletree/sparkletree-sdk/-/blob/main/README.md",
+  "bugs": {
+    "url": "https://gitlab.com/sparkletree/sparkletree-sdk/-/issues"
+  },
+  "keywords": [
+    "sparkletree",
+    "cli",
+    "components",
+    "scaffold",
+    "react"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "typecheck": "tsc --project tsconfig.json --noEmit"
+  }
+}