click-to-source-3d 0.0.0-stage → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Click-to-Source 3D
+
+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

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# click-to-source-3d
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sets up [Click-to-Source 3D](https://github.com/pun1th01/click-to-source-3d)
+in a Vite + React Three Fiber project with one command.
+
+    npx click-to-source-3d init
+
+Run it in your app's folder, the one with `package.json` and `vite.config`.
+It needs Node 20.19+, Vite 6–8, React Three Fiber 9 and three.js 0.170+.
+`pnpm dlx click-to-source-3d init` and `bunx click-to-source-3d init` work
+too.
+
+Then start your app as usual, press **Alt+Shift+C** (or the button in the
+corner of the canvas), and click any object to see the line that created it
+and edit its values.
+
+## What it does
+
+1. Installs `@click-to-source-3d/vite-plugin` as a dev dependency, with the
+   package manager your project uses (npm, pnpm, yarn or bun, from its
+   lockfile).
+2. Adds `clickToSource()` to the front of `plugins` in your `vite.config`,
+   changing nothing else in the file. If the config is written in a way it
+   cannot edit safely, it prints the two lines to add instead.
+3. Asks whether to set up the tools for AI coding assistants. On yes, it also
+   installs `@click-to-source-3d/mcp` and registers it in `.mcp.json` at your
+   repository root, which is Claude Code's config file. For Cursor, VS Code
+   and others, see the
+   [MCP package](https://www.npmjs.com/package/@click-to-source-3d/mcp).
+
+It stops before changing anything if the project does not use Vite, or does
+not use React Three Fiber. Running it again changes nothing.
+
+## Options
+
+    --mcp        set up the AI-assistant tools without asking
+    --no-mcp     do not ask about them
+    -y, --yes    accept the defaults without asking
+    --force      set up a project that does not use React Three Fiber
+    -h, --help   show help
+
+It is never added to your project: `npx` downloads it, runs it, and that is
+all.
+
+## License
+
+MIT

package/dist/bin.d.ts

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

package/dist/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// The executable. Kept apart from cli.ts so tests can import that without
+// running anything, and so nothing depends on comparing a module URL with
+// argv[1] — which an npm bin symlink makes differ on macOS and Linux.
+import { main } from "./cli.js";
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+});

package/dist/cli.d.ts

@@ -0,0 +1,34 @@
+export declare const VERSION: string;
+/** Everything init does to the outside world, so a test can stand in for it. */
+export type Io = {
+    cwd: string;
+    log: (line: string) => void;
+    error: (line: string) => void;
+    /** Runs a command to completion and returns its exit code. */
+    run: (command: string, args: string[], cwd: string) => number;
+    ask: (question: string) => Promise<string>;
+    interactive: boolean;
+    platform: NodeJS.Platform;
+};
+export type Flags = {
+    /** null: ask, when there is someone to ask. */
+    mcp: boolean | null;
+    yes: boolean;
+    force: boolean;
+    help: boolean;
+    version: boolean;
+    /** Package specs to install instead of the published ones — for testing unreleased builds. */
+    pluginSpec?: string;
+    mcpSpec?: string;
+};
+export declare function parseArgs(argv: string[]): {
+    command: string | null;
+    flags: Flags;
+    unknown: string[];
+};
+/**
+ * Installs the plugin, adds it to vite.config, and — if asked — registers the
+ * MCP server. Returns the process exit code.
+ */
+export declare function init(flags: Flags, io: Io): Promise<number>;
+export declare function main(argv: string[], io?: Io): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,185 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { MCP_PACKAGE, mcpServerEntry, mergeMcpConfig } from "./mcpConfig.js";
+import { installCommand, readProject } from "./project.js";
+import { MANUAL_SNIPPET, PLUGIN_PACKAGE, patchViteConfig } from "./viteConfig.js";
+export const VERSION = createRequire(import.meta.url)("../package.json").version;
+const MCP_SETUP_URL = "https://github.com/pun1th01/click-to-source-3d/tree/main/packages/mcp#install";
+export function parseArgs(argv) {
+    const flags = { mcp: null, yes: false, force: false, help: false, version: false };
+    const unknown = [];
+    let command = null;
+    for (const arg of argv) {
+        if (arg === "--mcp")
+            flags.mcp = true;
+        else if (arg === "--no-mcp")
+            flags.mcp = false;
+        else if (arg === "--yes" || arg === "-y")
+            flags.yes = true;
+        else if (arg === "--force")
+            flags.force = true;
+        else if (arg === "--help" || arg === "-h")
+            flags.help = true;
+        else if (arg === "--version" || arg === "-v")
+            flags.version = true;
+        else if (arg.startsWith("--plugin-spec="))
+            flags.pluginSpec = arg.slice("--plugin-spec=".length);
+        else if (arg.startsWith("--mcp-spec="))
+            flags.mcpSpec = arg.slice("--mcp-spec=".length);
+        else if (!arg.startsWith("-") && command === null)
+            command = arg;
+        else
+            unknown.push(arg);
+    }
+    return { command, flags, unknown };
+}
+const HELP = `click-to-source-3d ${VERSION}
+
+Sets up Click-to-Source 3D in a Vite + React Three Fiber project.
+
+Usage
+  npx click-to-source-3d init [options]
+
+Options
+  --mcp       Also set up the MCP server for AI coding assistants
+  --no-mcp    Do not ask about the MCP server
+  -y, --yes   Accept the defaults without asking
+  --force     Set up a project that does not use React Three Fiber
+  -h, --help  Show this help
+`;
+function devCommand(manager) {
+    return manager === "npm" ? "npm run dev" : `${manager} dev`;
+}
+/**
+ * Installs the plugin, adds it to vite.config, and — if asked — registers the
+ * MCP server. Returns the process exit code.
+ */
+export async function init(flags, io) {
+    const project = readProject(io.cwd);
+    if (!project) {
+        io.error(`No package.json in ${io.cwd}. Run this in your app's folder.`);
+        return 1;
+    }
+    if (!project.hasVite || !project.viteConfig) {
+        io.error(`${project.name} does not use Vite (no vite.config found). Click-to-Source 3D ` +
+            "works with Vite for now; webpack and Next.js are on the roadmap.");
+        return 1;
+    }
+    if (!project.hasR3F && !flags.force) {
+        io.error(`${project.name} does not use React Three Fiber. Plain three.js support arrives ` +
+            "in 0.2.0. Run with --force to set it up anyway.");
+        return 1;
+    }
+    const configName = path.basename(project.viteConfig);
+    io.log(`Setting up Click-to-Source 3D in ${project.name}\n`);
+    let mcp = flags.mcp;
+    if (mcp === null) {
+        mcp =
+            io.interactive && !flags.yes
+                ? /^y/i.test((await io.ask("Set up AI-agent tools (MCP)? (y/N) ")).trim())
+                : false;
+    }
+    const specs = [flags.pluginSpec ?? `${PLUGIN_PACKAGE}@^${VERSION}`];
+    if (mcp) {
+        specs.push(flags.mcpSpec ?? `${MCP_PACKAGE}@^${VERSION}`);
+    }
+    const { command, args } = installCommand(project.packageManager, specs);
+    io.log(`Installing with ${project.packageManager}: ${specs.join(" ")}`);
+    if (io.run(command, args, project.dir) !== 0) {
+        io.error(`\nThe install failed. Nothing else was changed. You can run it yourself:\n  ${command} ${args.join(" ")}`);
+        return 1;
+    }
+    io.log(`✔ Installed ${PLUGIN_PACKAGE}${mcp ? ` and ${MCP_PACKAGE}` : ""}`);
+    let manual = false;
+    const patch = patchViteConfig(readFileSync(project.viteConfig, "utf8"));
+    if (patch.status === "patched") {
+        writeFileSync(project.viteConfig, patch.code);
+        io.log(`✔ Added clickToSource() to ${configName}`);
+    }
+    else if (patch.status === "already") {
+        io.log(`✔ ${configName} already uses clickToSource()`);
+    }
+    else {
+        manual = true;
+        io.log(`! Could not edit ${configName} automatically: ${patch.reason}.\n` +
+            `  Add these lines to it:\n\n${MANUAL_SNIPPET.replace(/^/gm, "    ")}\n`);
+    }
+    if (mcp) {
+        const file = path.join(project.workspaceRoot, ".mcp.json");
+        const merged = mergeMcpConfig(existsSync(file) ? readFileSync(file, "utf8") : null, io.platform);
+        const where = path.relative(io.cwd, file) || ".mcp.json";
+        if (merged.status === "added") {
+            writeFileSync(file, merged.text);
+            io.log(`✔ Registered the MCP server in ${where}`);
+            io.log(`  Claude Code reads it. For Cursor, VS Code and others, see ${MCP_SETUP_URL}`);
+        }
+        else if (merged.status === "already") {
+            io.log(`✔ ${where} already registers the MCP server`);
+        }
+        else {
+            manual = true;
+            io.log(`! Could not edit ${where} (${merged.reason}). Add this under "mcpServers":\n\n` +
+                `    "click-to-source": ${JSON.stringify(mcpServerEntry(io.platform))}\n`);
+        }
+    }
+    io.log(`\n${manual ? "Almost done" : "Done"}. Start your app with \`${devCommand(project.packageManager)}\`, ` +
+        "then press Alt+Shift+C (or the button in the corner of the canvas) and click any object.");
+    return 0;
+}
+/**
+ * Quoting for cmd.exe. Package managers are .cmd scripts on Windows and have
+ * to run through the shell, where `^` is the escape character: unquoted,
+ * `pkg@^0.1.5` installs exactly 0.1.5.
+ */
+function quoteForCmd(arg) {
+    return /[\s^&|<>()%!"]/.test(arg) ? `"${arg.replace(/"/g, '\\"')}"` : arg;
+}
+function realIo() {
+    const windows = process.platform === "win32";
+    return {
+        cwd: process.cwd(),
+        log: (line) => console.log(line),
+        error: (line) => console.error(line),
+        // On Windows the command line is built here, quoted, and handed to the
+        // shell whole: passing an args array alongside shell: true is deprecated
+        // in Node 24, because Node would only concatenate it, unescaped.
+        run: (command, args, cwd) => (windows
+            ? spawnSync([command, ...args.map(quoteForCmd)].join(" "), { cwd, stdio: "inherit", shell: true })
+            : spawnSync(command, args, { cwd, stdio: "inherit" })).status ?? 1,
+        ask: async (question) => {
+            const readline = createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                return await readline.question(question);
+            }
+            finally {
+                readline.close();
+            }
+        },
+        interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        platform: process.platform,
+    };
+}
+export async function main(argv, io = realIo()) {
+    const { command, flags, unknown } = parseArgs(argv);
+    if (flags.version) {
+        io.log(VERSION);
+        return 0;
+    }
+    if (flags.help) {
+        io.log(HELP);
+        return 0;
+    }
+    if (unknown.length > 0) {
+        io.error(`Unknown option ${unknown[0]}.\n\n${HELP}`);
+        return 1;
+    }
+    // `npx click-to-source-3d` on its own does the one thing it is for.
+    if (command !== null && command !== "init") {
+        io.error(`Unknown command "${command}".\n\n${HELP}`);
+        return 1;
+    }
+    return init(flags, io);
+}

package/dist/mcpConfig.d.ts

@@ -0,0 +1,32 @@
+export declare const MCP_SERVER_NAME = "click-to-source";
+export declare const MCP_PACKAGE = "@click-to-source-3d/mcp";
+/**
+ * The `.mcp.json` entry that starts the MCP server.
+ *
+ * `npx -y <package>` runs the copy installed in the project when there is
+ * one, and fetches it otherwise, so the entry works from the repository root
+ * of a monorepo whose app is further down. On Windows, MCP clients spawn
+ * commands without a shell, and npx is a .cmd script there, so it has to go
+ * through `cmd /c`.
+ */
+export declare function mcpServerEntry(platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
+export type McpMergeResult = {
+    status: "added";
+    text: string;
+} | {
+    status: "already";
+} | {
+    status: "invalid";
+    reason: string;
+};
+/**
+ * Adds the server to an existing `.mcp.json`, or starts one.
+ *
+ * An existing entry of the same name is left as it is: the developer may
+ * have changed it. A file that is not valid JSON is never rewritten; the
+ * caller says what to add by hand instead.
+ */
+export declare function mergeMcpConfig(existing: string | null, platform?: NodeJS.Platform): McpMergeResult;

package/dist/mcpConfig.js

@@ -0,0 +1,43 @@
+export const MCP_SERVER_NAME = "click-to-source";
+export const MCP_PACKAGE = "@click-to-source-3d/mcp";
+/**
+ * The `.mcp.json` entry that starts the MCP server.
+ *
+ * `npx -y <package>` runs the copy installed in the project when there is
+ * one, and fetches it otherwise, so the entry works from the repository root
+ * of a monorepo whose app is further down. On Windows, MCP clients spawn
+ * commands without a shell, and npx is a .cmd script there, so it has to go
+ * through `cmd /c`.
+ */
+export function mcpServerEntry(platform = process.platform) {
+    const run = ["npx", "-y", MCP_PACKAGE];
+    return platform === "win32"
+        ? { command: "cmd", args: ["/c", ...run] }
+        : { command: run[0], args: run.slice(1) };
+}
+/**
+ * Adds the server to an existing `.mcp.json`, or starts one.
+ *
+ * An existing entry of the same name is left as it is: the developer may
+ * have changed it. A file that is not valid JSON is never rewritten; the
+ * caller says what to add by hand instead.
+ */
+export function mergeMcpConfig(existing, platform = process.platform) {
+    let config = {};
+    if (existing !== null && existing.trim() !== "") {
+        try {
+            config = JSON.parse(existing);
+        }
+        catch (error) {
+            return { status: "invalid", reason: error.message };
+        }
+        if (typeof config !== "object" || config === null || Array.isArray(config)) {
+            return { status: "invalid", reason: "it is not a JSON object" };
+        }
+    }
+    if (config.mcpServers && MCP_SERVER_NAME in config.mcpServers) {
+        return { status: "already" };
+    }
+    config.mcpServers = { ...(config.mcpServers ?? {}), [MCP_SERVER_NAME]: mcpServerEntry(platform) };
+    return { status: "added", text: `${JSON.stringify(config, null, 2)}\n` };
+}

package/dist/project.d.ts

@@ -0,0 +1,31 @@
+export type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
+export type Project = {
+    /** Directory holding the package.json init runs against. */
+    dir: string;
+    name: string;
+    packageManager: PackageManager;
+    /** Absolute path of the Vite config, if there is one. */
+    viteConfig: string | null;
+    hasVite: boolean;
+    hasR3F: boolean;
+    /**
+     * Where `.mcp.json` belongs: the repository root, since that is where an
+     * assistant is usually started — in a monorepo, above the app.
+     */
+    workspaceRoot: string;
+};
+/**
+ * The package manager a project uses: the nearest lockfile, looking up from
+ * the project to the repository root, since a monorepo keeps one lockfile at
+ * the top. With no lockfile — a project not installed yet — the manager that
+ * launched init, from the user agent it sets.
+ */
+export declare function detectPackageManager(dir: string, userAgent?: string): PackageManager;
+/** The nearest directory above `dir` holding .git, or `dir` itself. */
+export declare function findWorkspaceRoot(dir: string): string;
+export declare function readProject(dir: string): Project | null;
+/** The command that adds packages as dev dependencies. */
+export declare function installCommand(manager: PackageManager, specs: string[]): {
+    command: string;
+    args: string[];
+};

package/dist/project.js

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { VITE_CONFIG_NAMES } from "./viteConfig.js";
+const LOCKFILES = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"],
+    ["package-lock.json", "npm"],
+];
+/**
+ * The package manager a project uses: the nearest lockfile, looking up from
+ * the project to the repository root, since a monorepo keeps one lockfile at
+ * the top. With no lockfile — a project not installed yet — the manager that
+ * launched init, from the user agent it sets.
+ */
+export function detectPackageManager(dir, userAgent = process.env.npm_config_user_agent ?? "") {
+    for (let current = path.resolve(dir);; current = path.dirname(current)) {
+        for (const [file, manager] of LOCKFILES) {
+            if (existsSync(path.join(current, file))) {
+                return manager;
+            }
+        }
+        if (existsSync(path.join(current, ".git")) || path.dirname(current) === current) {
+            break;
+        }
+    }
+    const launcher = userAgent.split("/")[0];
+    return launcher === "pnpm" || launcher === "yarn" || launcher === "bun" ? launcher : "npm";
+}
+/** The nearest directory above `dir` holding .git, or `dir` itself. */
+export function findWorkspaceRoot(dir) {
+    for (let current = path.resolve(dir);; current = path.dirname(current)) {
+        if (existsSync(path.join(current, ".git"))) {
+            return current;
+        }
+        if (path.dirname(current) === current) {
+            return path.resolve(dir);
+        }
+    }
+}
+export function readProject(dir) {
+    const manifest = path.join(dir, "package.json");
+    if (!existsSync(manifest)) {
+        return null;
+    }
+    const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+    const deps = { ...pkg.peerDependencies, ...pkg.dependencies, ...pkg.devDependencies };
+    const config = VITE_CONFIG_NAMES.map((name) => path.join(dir, name)).find((file) => existsSync(file));
+    return {
+        dir,
+        name: pkg.name ?? path.basename(dir),
+        packageManager: detectPackageManager(dir),
+        viteConfig: config ?? null,
+        hasVite: "vite" in deps || config !== undefined,
+        hasR3F: "@react-three/fiber" in deps,
+        workspaceRoot: findWorkspaceRoot(dir),
+    };
+}
+/** The command that adds packages as dev dependencies. */
+export function installCommand(manager, specs) {
+    switch (manager) {
+        case "pnpm":
+            return { command: "pnpm", args: ["add", "-D", ...specs] };
+        case "yarn":
+            return { command: "yarn", args: ["add", "-D", ...specs] };
+        case "bun":
+            return { command: "bun", args: ["add", "-d", ...specs] };
+        default:
+            return { command: "npm", args: ["install", "-D", ...specs] };
+    }
+}

package/dist/viteConfig.d.ts

@@ -0,0 +1,26 @@
+export declare const PLUGIN_PACKAGE = "@click-to-source-3d/vite-plugin";
+export declare const MANUAL_SNIPPET: string;
+export type PatchResult = {
+    status: "patched";
+    code: string;
+} | {
+    status: "already";
+} | {
+    status: "unsupported";
+    reason: string;
+};
+/**
+ * Adds `clickToSource()` to the front of a Vite config's plugins.
+ *
+ * Edits only what it must — one import, one call — so the developer's own
+ * formatting survives untouched. Finds the config in the shapes Vite's own
+ * templates and docs use: `export default defineConfig({...})`, a plain
+ * object, a function returning one (arrow or with a body), and a config held
+ * in a variable and exported. Anything else is reported as unsupported
+ * rather than guessed at, and the caller prints the lines to paste.
+ *
+ * The result is checked, not assumed: a library that reported success here
+ * while adding only the import is why this exists.
+ */
+export declare function patchViteConfig(code: string): PatchResult;
+export declare const VITE_CONFIG_NAMES: string[];

package/dist/viteConfig.js

@@ -0,0 +1,145 @@
+import { parse } from "@babel/parser";
+import MagicString from "magic-string";
+export const PLUGIN_PACKAGE = "@click-to-source-3d/vite-plugin";
+export const MANUAL_SNIPPET = [
+    `import { clickToSource } from "${PLUGIN_PACKAGE}";`,
+    "",
+    "// first in the plugins array:",
+    "plugins: [clickToSource(), react()],",
+].join("\n");
+function keyName(property) {
+    const key = property.key;
+    if (!key || property.computed) {
+        return null;
+    }
+    if (key.type === "Identifier") {
+        return key.name;
+    }
+    if (key.type === "StringLiteral") {
+        return key.value;
+    }
+    return null;
+}
+/** The object a call such as defineConfig(...) is configured with, wherever it is written. */
+function configObject(node) {
+    if (!node) {
+        return null;
+    }
+    switch (node.type) {
+        case "ObjectExpression":
+            return node;
+        case "CallExpression":
+            // defineConfig({...}) and defineConfig(() => ...)
+            return configObject(node.arguments[0]);
+        case "ArrowFunctionExpression":
+        case "FunctionExpression": {
+            const body = node.body;
+            if (body.type !== "BlockStatement") {
+                return configObject(body);
+            }
+            const ret = body.body.find((statement) => statement.type === "ReturnStatement");
+            return configObject(ret?.argument);
+        }
+        case "TSAsExpression":
+        case "TSSatisfiesExpression":
+        case "ParenthesizedExpression":
+            return configObject(node.expression);
+        default:
+            return null;
+    }
+}
+/**
+ * Adds `clickToSource()` to the front of a Vite config's plugins.
+ *
+ * Edits only what it must — one import, one call — so the developer's own
+ * formatting survives untouched. Finds the config in the shapes Vite's own
+ * templates and docs use: `export default defineConfig({...})`, a plain
+ * object, a function returning one (arrow or with a body), and a config held
+ * in a variable and exported. Anything else is reported as unsupported
+ * rather than guessed at, and the caller prints the lines to paste.
+ *
+ * The result is checked, not assumed: a library that reported success here
+ * while adding only the import is why this exists.
+ */
+export function patchViteConfig(code) {
+    if (code.includes(PLUGIN_PACKAGE)) {
+        return { status: "already" };
+    }
+    let ast;
+    try {
+        ast = parse(code, {
+            sourceType: "module",
+            plugins: ["typescript", "jsx"],
+        }).program;
+    }
+    catch (error) {
+        return { status: "unsupported", reason: `could not parse it (${error.message})` };
+    }
+    const body = ast.body;
+    const exported = body.find((statement) => statement.type === "ExportDefaultDeclaration");
+    if (!exported) {
+        return { status: "unsupported", reason: "it has no `export default`" };
+    }
+    let declaration = exported.declaration;
+    // `const config = defineConfig({...}); export default config`
+    if (declaration.type === "Identifier") {
+        for (const statement of body) {
+            if (statement.type !== "VariableDeclaration") {
+                continue;
+            }
+            for (const declarator of statement.declarations) {
+                const id = declarator.id;
+                if (id.type === "Identifier" && id.name === declaration.name && declarator.init) {
+                    declaration = declarator.init;
+                }
+            }
+        }
+    }
+    const config = configObject(declaration);
+    if (!config) {
+        return { status: "unsupported", reason: "its exported config is not an object Vite's templates write" };
+    }
+    const magic = new MagicString(code);
+    const properties = config.properties;
+    const plugins = properties.find((property) => property.type === "ObjectProperty" && keyName(property) === "plugins");
+    if (plugins) {
+        const value = plugins.value;
+        if (value.type !== "ArrayExpression") {
+            return { status: "unsupported", reason: "its `plugins` is not an array literal" };
+        }
+        const elements = value.elements;
+        magic.appendLeft(value.start + 1, elements.length > 0 ? "clickToSource(), " : "clickToSource()");
+    }
+    else {
+        magic.appendLeft(config.start + 1, "\n  plugins: [clickToSource()],");
+    }
+    // The import goes after the last one already there, or first.
+    const imports = body.filter((statement) => statement.type === "ImportDeclaration");
+    const statement = `import { clickToSource } from "${PLUGIN_PACKAGE}";`;
+    if (imports.length > 0) {
+        magic.appendLeft(imports[imports.length - 1].end, `\n${statement}`);
+    }
+    else {
+        magic.prepend(`${statement}\n`);
+    }
+    const patched = magic.toString();
+    // The guarantee: the plugin is called inside the config's plugins.
+    try {
+        parse(patched, { sourceType: "module", plugins: ["typescript", "jsx"] });
+    }
+    catch {
+        return { status: "unsupported", reason: "the edit did not produce valid code" };
+    }
+    if (!/plugins\s*:\s*\[\s*clickToSource\(\)/.test(patched)) {
+        return { status: "unsupported", reason: "the plugin could not be placed in `plugins`" };
+    }
+    return { status: "patched", code: patched };
+}
+export const VITE_CONFIG_NAMES = [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vite.config.js",
+    "vite.config.mjs",
+    "vite.config.cts",
+    "vite.config.cjs",
+];

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "click-to-source-3d",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.5",
+  "description": "Set up Click-to-Source 3D in a Vite + React Three Fiber project with one command",
+  "keywords": [
+    "threejs",
+    "react-three-fiber",
+    "r3f",
+    "vite",
+    "devtools",
+    "inspector"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "click-to-source-3d": "dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pun1th01/click-to-source-3d.git",
+    "directory": "packages/cli"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "clean": "node -e \"const f=require('fs');f.rmSync('dist',{recursive:true,force:true});f.rmSync('tsconfig.tsbuildinfo',{force:true})\"",
+    "build": "tsc -b",
+    "prepack": "npm run clean && tsc -b",
+    "prepublishOnly": "npm run test",
+    "pretest": "tsc -b",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "vitest": "^4.1.11"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.29.9",
+    "magic-string": "^0.30.21"
+  }
+}