create-addfox-app 0.2.1 → 0.2.3

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,7 @@
+#!/usr/bin/env node
+export declare function resolveLatestVersion(pkgName: string): string | null;
+export declare function updatePackageVersions(destDir: string, versions?: {
+    addfox?: string | null;
+    utils?: string | null;
+}): void;
+export declare function runCreateApp(rawArgv?: string[]): Promise<void>;

package/dist/cli.js

@@ -212,6 +212,12 @@ const FRAMEWORKS = [
 function getTemplateName(framework, language) {
     return `template-${framework}-${language}`;
 }
+const PACKAGE_MANAGER_ORDER = [
+    "pnpm",
+    "npm",
+    "yarn",
+    "bun"
+];
 const PACKAGE_MANAGER_CHOICES = [
     {
         title: "pnpm",
@@ -826,6 +832,7 @@ function printHelp() {
   Create a new addfox extension project
 
   Usage:
+    addfox create [project-name] [options]
     create-addfox-app [project-name] [options]
 
   Options:
@@ -906,6 +913,7 @@ async function promptOptions() {
             name: "packageManager",
             message: "Select package manager",
             choices: getPackageManagerChoicesColored(),
+            initial: Math.max(0, PACKAGE_MANAGER_ORDER.indexOf(detectPackageManager())),
             hint: PROMPT_SELECT_HINT
         },
         {
@@ -987,19 +995,60 @@ function updatePackageName(destDir, projectName) {
     pkg.name = projectName.replace(/\s+/g, "-").toLowerCase();
     writeJsonFile(pkgPath, pkg);
 }
-async function main() {
-    const argv = parseArgv(process.argv.slice(2));
+function resolveLatestVersion(pkgName) {
+    try {
+        const output = execSync(`npm view ${pkgName} version --registry https://registry.npmjs.org/`, {
+            encoding: "utf-8",
+            stdio: [
+                "pipe",
+                "pipe",
+                "ignore"
+            ],
+            timeout: 3000
+        });
+        const version = output.trim();
+        return version || null;
+    } catch  {
+        return null;
+    }
+}
+function updatePackageVersions(destDir, versions = {}) {
+    const pkgPath = external_node_path_resolve(destDir, "package.json");
+    if (!existsSync(pkgPath)) return;
+    const addfoxVersion = versions.addfox ?? resolveLatestVersion("addfox");
+    const utilsVersion = versions.utils ?? resolveLatestVersion("@addfox/utils");
+    if (!addfoxVersion && !utilsVersion) return;
+    const pkg = readJsonFile(pkgPath);
+    if (addfoxVersion && pkg.devDependencies && "object" == typeof pkg.devDependencies) {
+        const devDeps = pkg.devDependencies;
+        if (devDeps["addfox"]) devDeps["addfox"] = `^${addfoxVersion}`;
+    }
+    if (utilsVersion) {
+        if (pkg.dependencies && "object" == typeof pkg.dependencies) {
+            const deps = pkg.dependencies;
+            if (deps["@addfox/utils"]) deps["@addfox/utils"] = `^${utilsVersion}`;
+        }
+        if (pkg.devDependencies && "object" == typeof pkg.devDependencies) {
+            const devDeps = pkg.devDependencies;
+            if (devDeps["@addfox/utils"]) devDeps["@addfox/utils"] = `^${utilsVersion}`;
+        }
+    }
+    writeJsonFile(pkgPath, pkg);
+}
+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 +1063,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 +1081,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);
@@ -1050,6 +1098,7 @@ async function main() {
     } else configContent = generateAddfoxConfig(options.framework, options.language, options.styleEngine);
     writeFileSync(configPath, configContent, "utf-8");
     updatePackageName(root, targetDir);
+    updatePackageVersions(root);
     applyStyleEngine(root, options.framework, options.language, options.styleEngine);
     applyTestAndReportSetup(root, options.language, testSelection);
     const installCmd = getInstallCommand(pm);
@@ -1090,7 +1139,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 { resolveLatestVersion, runCreateApp, updatePackageVersions };

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.1",
+  "version": "0.2.3",
   "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.1"
+    "@addfox/pkg-manager": "0.2.3"
   },
   "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": {