create-addfox-app 0.2.0 → 0.2.2

package/README.md

@@ -10,7 +10,8 @@
 
 Interactive scaffolder: generates a addfox-based extension project from options (template, package manager, entries, skills).
 
-- Commands: `create-addfox-app` or `pnpm create addfox-app` (and npm/yarn/bun equivalents)
+- Commands: `addfox create` or `npx addfox@latest create` (subcommand mode)
+- Legacy: `create-addfox-app` or `pnpm create addfox-app` (and npm/yarn/bun equivalents)
 - Flow: (1) select framework (vanilla / vue / react / preact / svelte / solid), (2) language (TypeScript / JavaScript), (3) package manager (pnpm / npm / yarn / bun), (4) entries to include (multi-select), (5) whether to install addfox skills (yes/no). Output to cwd or a given directory. Generated project uses **addfox.config.ts** or **addfox.config.js** with minimal manifest (entry discovery; no built-in entry paths in manifest).
 
 ## Templates

package/dist/cli/index.d.ts

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

package/dist/cli.js

@@ -826,6 +826,7 @@ function printHelp() {
   Create a new addfox extension project
 
   Usage:
+    addfox create [project-name] [options]
     create-addfox-app [project-name] [options]
 
   Options:
@@ -987,19 +988,20 @@ function updatePackageName(destDir, projectName) {
     pkg.name = projectName.replace(/\s+/g, "-").toLowerCase();
     writeJsonFile(pkgPath, pkg);
 }
-async function main() {
-    const argv = parseArgv(process.argv.slice(2));
+async function runCreateApp(rawArgv = process.argv.slice(2)) {
+    const argv = parseArgv(rawArgv);
     if (argv.help || argv.h) return void printHelp();
     if (argv.version || argv.v) return void console.log(getVersion());
-    const targetDir = argv._[0] ?? "my-extension";
+    const targetDir = String(argv._[0] ?? "my-extension");
     const cliFramework = argv.framework;
     const cliLanguage = argv.language;
+    console.log(dim(`  create-addfox-app v${getVersion()}`));
     printAddfoxLogo();
     console.log(blue("\n  Create Addfox App\n"));
     const root = external_node_path_resolve(process.cwd(), targetDir);
     if (existsSync(root)) {
         const confirmed = await confirmOverwrite(targetDir);
-        if (!confirmed) process.exit(0);
+        if (!confirmed) return;
         rmSync(root, {
             recursive: true,
             force: true
@@ -1014,9 +1016,9 @@ async function main() {
             "__all__"
         ]
     } : await promptOptions();
-    if (!options) process.exit(0);
+    if (!options) return;
     const testSelection = cliFramework && cliLanguage ? resolveTestSelectionFromArgv(argv) : await promptTestAndReport();
-    if (!testSelection) process.exit(0);
+    if (!testSelection) return;
     const pm = options.packageManager;
     const templateName = getTemplateName(options.framework, options.language);
     const templateReady = hasLocalTemplate(templateName);
@@ -1032,8 +1034,7 @@ async function main() {
             minVisibleMs: TEMPLATE_SPINNER_MIN_MS
         } : void 0);
     } catch (err) {
-        console.error(red(`\n  Failed to copy template: ${err.message}\n`));
-        process.exit(1);
+        throw new Error(`Failed to copy template: ${err.message}`);
     }
     const useAllEntries = options.entries.includes("__all__");
     const existingDirs = getExistingAppEntryDirs(root);
@@ -1090,7 +1091,12 @@ async function main() {
     console.log(`  ${installCmd}`);
     console.log(`  ${devCmd}\n`);
 }
-main().catch((e)=>{
+async function main() {
+    await runCreateApp();
+}
+const isCli = import.meta.url.startsWith("file://") && process.argv[1] === fileURLToPath(import.meta.url);
+if (isCli) main().catch((e)=>{
     console.error(e);
     process.exit(1);
 });
+export { runCreateApp };

package/dist/config/dependencyRanges.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Published dependency ranges (caret baseline) for scaffold `package.json` under `create-addfox-app/templates/`.
+ * Bump when releasing new versions of `addfox`, `@addfox/utils`, or `@rsbuild/plugin-vue` in templates.
+ *
+ * Templates put `addfox` and `@rsbuild/plugin-*` in **devDependencies** (build-time only).
+ * `@addfox/utils` is in **dependencies** so extension runtime code can import it.
+ * Do **not** list `@rsbuild/core` in templates: it is pulled in by `addfox` → `@addfox/cli` / `@addfox/core`
+ * and satisfies peers for Rsbuild plugins.
+ *
+ * `ADDFOX_0_1_SCAFFOLD_RANGE` is a semver range for tooling/docs that must accept 0.1.x prereleases.
+ */
+export declare const ADDFOX_CLI_PACKAGE_VERSION: "^0.2.0";
+export declare const ADDFOX_UTILS_PACKAGE_VERSION: "^0.2.0";
+/** `@rsbuild/plugin-vue` range in `template-vue-ts` / `template-vue-js` (aligned across JS/TS). */
+export declare const RSBUILD_PLUGIN_VUE_PACKAGE_VERSION: "^1.2.8";
+/**
+ * `^0.2.0` matches stable releases in the 0.2.x line.
+ */
+export declare const ADDFOX_0_1_SCAFFOLD_RANGE: ">=0.2.0-0 <0.3.0";

package/dist/config/generate.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Full `addfox.config` codegen when the template has no usable file (fallback only).
+ * Normal scaffold: the template’s addfox.config is kept and merged (see `./merge.ts`).
+ */
+import type { Framework, Language, StyleEngine } from "../template/catalog.ts";
+export declare function getStylePlugin(engine: StyleEngine | undefined): {
+    importLine: string;
+    call: string;
+} | null;
+export declare function generateAddfoxConfig(framework: Framework, _language: Language, styleEngine?: StyleEngine): string;

package/dist/config/merge.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Merges scaffold-time changes into an existing addfox.config from the template
+ * (preserves manifest and framework plugins; only injects Less/Sass Rsbuild plugins when selected).
+ */
+import type { StyleEngine } from "../template/catalog.ts";
+/**
+ * After copying a template, merge only Less/Sass Rsbuild plugins into the existing config.
+ * Tailwind/UnoCSS need no changes here (postcss + applyStyleEngine). Manifest stays as in template.
+ */
+export declare function mergeScaffoldIntoAddfoxConfig(source: string, styleEngine: StyleEngine): string;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { runCreateApp } from "./cli/index.ts";

package/dist/index.js

@@ -0,0 +1 @@
+export { runCreateApp } from "./cli.js";

package/dist/lib/colors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Lightweight ANSI color helpers.
+ * Replaces the `kolorist` npm package to reduce supply-chain risk.
+ */
+export declare const black: (s: string) => string;
+export declare const red: (s: string) => string;
+export declare const green: (s: string) => string;
+export declare const yellow: (s: string) => string;
+export declare const blue: (s: string) => string;
+export declare const magenta: (s: string) => string;
+export declare const cyan: (s: string) => string;
+export declare const white: (s: string) => string;
+export declare const gray: (s: string) => string;
+export declare const lightRed: (s: string) => string;
+export declare const lightGreen: (s: string) => string;
+export declare const lightYellow: (s: string) => string;
+export declare const lightBlue: (s: string) => string;
+export declare const lightMagenta: (s: string) => string;
+export declare const lightCyan: (s: string) => string;
+export declare const lightGray: (s: string) => string;
+export declare const dim: (s: string) => string;
+/** True-color (24-bit) helper. */
+export declare function trueColor(r: number, g: number, b: number): (s: string) => string;

package/dist/lib/jsonFile.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Read/write JSON files; strips UTF-8 BOM on read so JSON.parse never fails.
+ */
+export declare function stripUtf8Bom(text: string): string;
+export declare function readJsonFile<T = unknown>(path: string): T;
+export declare function writeJsonFile(path: string, data: unknown): void;

package/dist/lib/minimist.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Minimal argv parser.
+ * Replaces the `minimist` npm package to reduce supply-chain risk.
+ */
+export interface ParsedArgv {
+    _: (string | number)[];
+    [key: string]: string | number | boolean | (string | number)[] | undefined;
+}
+export declare function parseArgv(argv: string[]): ParsedArgv;

package/dist/prompts/logo.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CLI banner: FIGlet-style block letters (same family as Vercel skills CLI).
+ *
+ * Uses **256-color** ANSI (`\x1b[38;5;Nm`) for the orange→pink gradient, not 24-bit
+ * truecolor (`38;2;r;g;b`). Apple Terminal + zsh often mishandle or strip truecolor;
+ * Vercel `skills` uses per-line 256-color grays for the same reason.
+ *
+ * @see https://github.com/vercel-labs/skills/blob/main/src/cli.ts (showLogo / GRAYS)
+ */
+export declare function printAddfoxLogo(): void;

package/dist/prompts/packageManager.d.ts

@@ -0,0 +1,6 @@
+import type { PackageManager } from "@addfox/pkg-manager";
+export declare const PACKAGE_MANAGER_ORDER: PackageManager[];
+export declare const PACKAGE_MANAGER_CHOICES: {
+    title: string;
+    value: PackageManager;
+}[];

package/dist/prompts/skills.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Skills step: fetch addfox/skills list and run skills add via package manager.
+ */
+export interface SkillItem {
+    name: string;
+    value: string;
+}
+/** Fetch list of skill names (directories with SKILL.md) from addfox/skills. */
+export declare function fetchSkillsList(): Promise<SkillItem[]>;
+export declare function getSkillsChoices(skills: SkillItem[]): {
+    title: string;
+    value: string;
+}[];
+/** Build the skills add command args: repo or repo/skill1 repo/skill2 ... */
+export declare function getSkillsAddArgs(selected: string[]): string[];

package/dist/scaffold/entries.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Extension entry types supported by create-addfox-app.
+ * Matches addfox MANIFEST_ENTRY_KEYS; app/ subdir names align with these.
+ */
+export declare const ENTRY_NAMES: readonly ["popup", "options", "background", "content", "devtools", "sidepanel", "sandbox", "newtab", "bookmarks", "history", "offscreen"];
+export type EntryName = (typeof ENTRY_NAMES)[number];
+/** app/ directory name for each entry (same as entry name) */
+export declare const ENTRY_APP_DIRS: readonly EntryName[];
+export declare const ENTRY_CHOICES: {
+    title: string;
+    value: string;
+}[];
+/** Entries that require extra permissions when added to manifest */
+export declare const ENTRY_EXTRA_PERMISSIONS: Record<string, string[]>;

package/dist/scaffold/style.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Apply selected style engine after template copy: deps, config files, and entry imports.
+ */
+import type { Framework, Language, StyleEngine } from "../template/catalog.ts";
+export declare function applyStyleEngine(root: string, _framework: Framework, language: Language, engine: StyleEngine): void;

package/dist/scaffold/test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Optional rstest + Rsdoctor setup for scaffolded projects.
+ * Versions align with @rstest/core usage in this monorepo.
+ */
+import type { Language } from "../template/catalog.ts";
+export type TestKind = "unit" | "e2e";
+export interface TestSetupSelection {
+    testKinds: TestKind[];
+    installRsdoctor: boolean;
+}
+export declare function generateRstestConfig(language: Language, testKinds: TestKind[]): string;
+export declare function applyTestAndReportSetup(root: string, language: Language, selection: TestSetupSelection): void;

package/dist/template/bundledCopy.d.ts

@@ -0,0 +1,13 @@
+/** True if the bundled `templates/<name>` directory exists in this package. */
+export declare function hasLocalTemplate(templateName: string): boolean;
+/**
+ * Skip dependency trees and VCS **inside the template folder** when copying.
+ * Must use paths relative to `templateRoot`: the install path often contains
+ * `.pnpm` / `node_modules` (e.g. pnpm store), which must not cause every file to be skipped.
+ */
+export declare function shouldCopyLocalTemplatePath(src: string, templateRoot: string): boolean;
+/**
+ * Copy bundled template from node_modules/create-addfox-app/templates into destDir.
+ * @throws If the template folder is missing (broken install or forgot to run build).
+ */
+export declare function copyBundledTemplate(templateName: string, destDir: string): Promise<void>;

package/dist/template/catalog.d.ts

@@ -0,0 +1,17 @@
+export type Framework = "vanilla" | "vue" | "react" | "preact" | "svelte" | "solid";
+export type Language = "js" | "ts";
+/** Style / CSS tooling (after framework). `none` = no extra style stack. */
+export type StyleEngine = "none" | "tailwindcss" | "unocss" | "less" | "sass";
+export declare const STYLE_ENGINES: {
+    title: string;
+    value: StyleEngine;
+}[];
+export declare const FRAMEWORKS: {
+    title: string;
+    value: Framework;
+}[];
+export declare const LANGUAGES: {
+    title: string;
+    value: Language;
+}[];
+export declare function getTemplateName(framework: Framework, language: Language): string;

package/dist/template/filterEntries.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Removes app/ entry dirs that are not in the selected entries list.
+ * Call after copying template when user did not select "all" entries.
+ */
+export declare function filterAppEntries(destDir: string, selectedEntries: string[]): void;
+/** Returns entry dir names that exist under app/ in the template. */
+export declare function getExistingAppEntryDirs(destDir: string): string[];

package/dist/template/spinner.d.ts

@@ -0,0 +1,12 @@
+export type TemplateSpinnerOptions = {
+    /**
+     * Keep the spinner visible at least this long after `fn` starts.
+     * Use for fast local copies so the animation is noticeable (sync work used to block the spinner).
+     */
+    minVisibleMs?: number;
+};
+/**
+ * Runs `fn` while showing a Braille-dot spinner + label on one terminal line.
+ * No-op animation when stdout is not a TTY (e.g. CI).
+ */
+export declare function runWithTemplateSpinner<T>(label: string, fn: () => Promise<T>, options?: TemplateSpinnerOptions): Promise<T>;

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "create-addfox-app",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Interactive scaffolder for addfox extension projects",
   "license": "MIT",
   "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./cli": "./dist/cli.js"
+  },
   "bin": {
     "create-addfox-app": "./dist/cli.js"
   },
@@ -14,7 +19,7 @@
   ],
   "dependencies": {
     "prompts": "^2.4.2",
-    "@addfox/pkg-manager": "0.2.0"
+    "@addfox/pkg-manager": "0.2.2"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -24,6 +29,7 @@
     "@rstest/core": "^0.9.9",
     "@rstest/coverage-istanbul": "^0.3.2",
     "@types/node": "^20.0.0",
+    "@types/prompts": "^2.4.9",
     "typescript": "^5.0.0"
   },
   "scripts": {

package/templates/template-preact-js/package.json

@@ -8,11 +8,11 @@
     "build": "addfox build"
   },
   "dependencies": {
-    "@addfox/utils": "0.1.1",
+    "@addfox/utils": "^0.2.0",
     "preact": "^10.29.0"
   },
   "devDependencies": {
-    "addfox": "0.1.1",
+    "addfox": "^0.2.0",
     "@rsbuild/plugin-preact": "1.7.2"
   }
 }

package/templates/template-preact-ts/package.json

@@ -8,11 +8,11 @@
     "build": "addfox build"
   },
   "dependencies": {
-    "@addfox/utils": "0.1.1",
+    "@addfox/utils": "^0.2.0",
     "preact": "^10.29.0"
   },
   "devDependencies": {
-    "addfox": "0.1.1",
+    "addfox": "^0.2.0",
     "@rsbuild/plugin-preact": "1.7.2",
     "typescript": "^5.9.3",
     "@types/chrome": "^0.1.38"

package/templates/template-react-js/package.json

@@ -8,12 +8,12 @@
     "build": "addfox build"
   },
   "dependencies": {
-    "@addfox/utils": "0.1.1",
+    "@addfox/utils": "^0.2.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4"
   },
   "devDependencies": {
-    "addfox": "0.1.1",
+    "addfox": "^0.2.0",
     "@rsbuild/plugin-react": "2.0.0"
   }
 }

package/templates/template-react-ts/package.json

@@ -8,12 +8,12 @@
     "build": "addfox build"
   },
   "dependencies": {
-    "@addfox/utils": "0.1.1",
+    "@addfox/utils": "^0.2.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4"
   },
   "devDependencies": {
-    "addfox": "0.1.1",
+    "addfox": "^0.2.0",
     "@rsbuild/plugin-react": "2.0.0",
     "typescript": "^5.9.3",
     "@types/chrome": "^0.1.38",

package/templates/template-solid-js/package.json

@@ -8,11 +8,11 @@
     "build": "addfox build"
   },
   "dependencies": {
-    "@addfox/utils": "0.1.1",
+    "@addfox/utils": "^0.2.0",
     "solid-js": "^1.9.11"
   },
   "devDependencies": {
-    "addfox": "0.1.1",
+    "addfox": "^0.2.0",
     "@rsbuild/plugin-babel": "^1.2.0",
     "@rsbuild/plugin-solid": "1.2.0"
   }

package/templates/template-solid-ts/package.json

@@ -8,11 +8,11 @@
     "build": "addfox build"
   },
   "dependencies": {
-    "@addfox/utils": "0.1.1",
+    "@addfox/utils": "^0.2.0",
     "solid-js": "^1.9.11"
   },
   "devDependencies": {
-    "addfox": "0.1.1",
+    "addfox": "^0.2.0",
     "@rsbuild/plugin-babel": "^1.2.0",
     "@rsbuild/plugin-solid": "1.2.0",
     "typescript": "^5.9.3",

package/templates/template-svelte-js/package.json

@@ -8,11 +8,11 @@
     "build": "addfox build"
   },
   "dependencies": {
-    "@addfox/utils": "0.1.1",
+    "@addfox/utils": "^0.2.0",
     "svelte": "^5.54.1"
   },
   "devDependencies": {
-    "addfox": "0.1.1",
+    "addfox": "^0.2.0",
     "@rsbuild/plugin-svelte": "1.1.1"
   }
 }

package/templates/template-svelte-ts/package.json

@@ -8,11 +8,11 @@
     "build": "addfox build"
   },
   "dependencies": {
-    "@addfox/utils": "0.1.1",
+    "@addfox/utils": "^0.2.0",
     "svelte": "^5.54.1"
   },
   "devDependencies": {
-    "addfox": "0.1.1",
+    "addfox": "^0.2.0",
     "@rsbuild/plugin-svelte": "1.1.1",
     "typescript": "^5.9.3",
     "@types/chrome": "^0.1.38"

package/templates/template-vanilla-js/package.json

@@ -8,6 +8,6 @@
     "build": "addfox build"
   },
   "devDependencies": {
-    "addfox": "0.1.1"
+    "addfox": "^0.2.0"
   }
 }

package/templates/template-vanilla-ts/package.json

@@ -8,7 +8,7 @@
     "build": "addfox build"
   },
   "devDependencies": {
-    "addfox": "0.1.1",
+    "addfox": "^0.2.0",
     "typescript": "^5.9.3"
   }
 }

package/templates/template-vue-js/package.json

@@ -8,11 +8,11 @@
     "build": "addfox build"
   },
   "dependencies": {
-    "@addfox/utils": "0.1.1",
+    "@addfox/utils": "^0.2.0",
     "vue": "^3.5.30"
   },
   "devDependencies": {
-    "addfox": "0.1.1",
+    "addfox": "^0.2.0",
     "@rsbuild/plugin-vue": "^1.2.8"
   }
 }

package/templates/template-vue-ts/package.json

@@ -8,11 +8,11 @@
     "build": "addfox build"
   },
   "dependencies": {
-    "@addfox/utils": "0.1.1",
+    "@addfox/utils": "^0.2.0",
     "vue": "^3.5.30"
   },
   "devDependencies": {
-    "addfox": "0.1.1",
+    "addfox": "^0.2.0",
     "@rsbuild/plugin-vue": "^1.2.8",
     "typescript": "^5.9.3",
     "@types/chrome": "^0.1.38"