@floegence/floe-webapp-init 0.33.0 → 0.33.2

package/dist/index.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import t from"node:fs";import a from"node:path";import{fileURLToPath as d}from"node:url";import y from"prompts";import{red as c,bold as g,cyan as f,green as x}from"kolorist";const h=[{name:"minimal",value:"minimal",description:"Basic setup with FloeApp"},{name:"full",value:"full",description:"Full setup with sample pages"}],v={"_package.json":"package.json",_gitignore:".gitignore","_env.example":".env.example",_claude:".claude"};async function S(){console.log(`
-${g(f("Floe Webapp"))}
-`);const n=process.argv.slice(2);let o=n[0],l;(n.includes("--help")||n.includes("-h"))&&(console.log(`Usage: npx @floegence/floe-webapp-init [project-name] [options]
+import n from"node:fs";import c from"node:path";import{fileURLToPath as d}from"node:url";import S from"prompts";import{red as a,bold as f,cyan as y,green as v}from"kolorist";const h=[{name:"minimal",value:"minimal",description:"Basic setup with FloeApp"},{name:"full",value:"full",description:"Full setup with sample pages"}],j={"_package.json":"package.json",_gitignore:".gitignore","_env.example":".env.example"};async function b(){console.log(`
+${f(y("Floe Webapp"))}
+`);const l=process.argv.slice(2);let o=l[0],t;(l.includes("--help")||l.includes("-h"))&&(console.log(`Usage: npx @floegence/floe-webapp-init [project-name] [options]
 
 Options:
   --template <name>  Use a specific template (minimal, full)
@@ -11,12 +11,14 @@ Examples:
   npx @floegence/floe-webapp-init
   npx @floegence/floe-webapp-init my-app
   npx @floegence/floe-webapp-init my-app --template full
-`),process.exit(0));const i=n.indexOf("--template");if(i!==-1&&n[i+1]){const e=n[i+1];e==="minimal"||e==="full"?l=e:(console.log(c(`Invalid template: ${e}`)),console.log("Available templates: minimal, full"),process.exit(1)),o==="--template"&&(o=n[i+2])}const p=await y([{type:o?null:"text",name:"projectName",message:"Project name:",initial:"floe-app",validate:e=>e?/^[a-z0-9-_]+$/i.test(e)?!0:"Project name can only contain letters, numbers, hyphens, and underscores":"Project name is required"},{type:l?null:"select",name:"template",message:"Select a template:",choices:h.map(e=>({title:e.name,value:e.value,description:e.description}))}],{onCancel:()=>{console.log(c(`
-Operation cancelled`)),process.exit(1)}});o=o||p.projectName,l=l||p.template,(!o||!l)&&(console.log(c("Missing required information")),process.exit(1));const s=a.resolve(o);t.existsSync(s)&&t.readdirSync(s).length>0&&(console.log(c(`
+`),process.exit(0));const i=l.indexOf("--template");if(i!==-1&&l[i+1]){const e=l[i+1];e==="minimal"||e==="full"?t=e:(console.log(a(`Invalid template: ${e}`)),console.log("Available templates: minimal, full"),process.exit(1)),o==="--template"&&(o=l[i+2])}const p=await S([{type:o?null:"text",name:"projectName",message:"Project name:",initial:"floe-app",validate:e=>e?/^[a-z0-9-_]+$/i.test(e)?!0:"Project name can only contain letters, numbers, hyphens, and underscores":"Project name is required"},{type:t?null:"select",name:"template",message:"Select a template:",choices:h.map(e=>({title:e.name,value:e.value,description:e.description}))}],{onCancel:()=>{console.log(a(`
+Operation cancelled`)),process.exit(1)}});o=o||p.projectName,t=t||p.template,(!o||!t)&&(console.log(a("Missing required information")),process.exit(1));const s=c.resolve(o);n.existsSync(s)&&n.readdirSync(s).length>0&&(console.log(a(`
 Directory ${o} is not empty.`)),process.exit(1)),console.log(`
-Scaffolding project in ${f(s)}...
-`);const r=a.resolve(d(import.meta.url),"../../templates",l);t.existsSync(r)||(console.log(c(`Template directory not found: ${r}`)),process.exit(1)),u(r,s);const m=a.join(s,"package.json");if(t.existsSync(m)){const e=JSON.parse(t.readFileSync(m,"utf-8"));e.name=a.basename(o),t.writeFileSync(m,JSON.stringify(e,null,2)+`
-`)}console.log(x(`Done!
+Scaffolding project in ${y(s)}...
+`);const r=c.resolve(d(import.meta.url),"../../templates",t),m=c.resolve(d(import.meta.url),"../../skills");n.existsSync(r)||(console.log(a(`Template directory not found: ${r}`)),process.exit(1)),u(r,s);const x=c.join(s,"skills");n.existsSync(m)?u(m,x):console.log(a(`Warning: skill directory not found: ${m}`));const g=c.join(s,"package.json");if(n.existsSync(g)){const e=JSON.parse(n.readFileSync(g,"utf-8"));e.name=c.basename(o),n.writeFileSync(g,JSON.stringify(e,null,2)+`
+`)}console.log(v(`Done!
 `)),console.log(`Next steps:
-`),console.log(`  cd ${g(o)}`),console.log("  pnpm install"),console.log(`  pnpm dev
-`)}function u(n,o){t.mkdirSync(o,{recursive:!0});for(const l of t.readdirSync(n)){const i=a.join(n,l),p=v[l]||l,s=a.join(o,p);t.statSync(i).isDirectory()?u(i,s):t.copyFileSync(i,s)}}S().catch(n=>{console.error(c("Error:"),n),process.exit(1)});
+`),console.log(`  cd ${f(o)}`),console.log("  pnpm install"),console.log(`  pnpm dev
+`),console.log(`Skill package:
+`),console.log(`  ${f("skills/floe-webapp/SKILL.md")}
+`)}function u(l,o){n.mkdirSync(o,{recursive:!0});for(const t of n.readdirSync(l)){const i=c.join(l,t),p=j[t]||t,s=c.join(o,p);n.statSync(i).isDirectory()?u(i,s):n.copyFileSync(i,s)}}b().catch(l=>{console.error(a("Error:"),l),process.exit(1)});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/floe-webapp-init",
-  "version": "0.33.0",
+  "version": "0.33.2",
   "type": "module",
   "description": "Scaffolding tool for Floe Webapp applications",
   "repository": {
@@ -14,7 +14,8 @@
   "main": "./dist/index.mjs",
   "files": [
     "dist",
-    "templates"
+    "templates",
+    "skills"
   ],
   "scripts": {
     "build": "unbuild",

package/skills/floe-webapp/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: floe-webapp
+description: Implement, refactor, and debug Floe-Webapp Solid.js applications with @floegence/floe-webapp-core public exports. Use for FloeApp shell wiring, FloeComponent sidebar or command registration, lifecycle hooks, design-token-first styling, and build or typecheck failures in Floe-Webapp projects.
+---
+
+# Floe-Webapp Skill
+
+## Scope
+
+- Implement or refactor pages/components in a Floe-Webapp app.
+- Add or update `FloeComponent` registration (`sidebar`, `commands`, lifecycle hooks).
+- Diagnose framework-usage issues and local build/lint/typecheck/test failures.
+
+## Required Inputs
+
+- Read project-root `AGENTS.md` first when available.
+- If `AGENTS.md` is absent, read `README.md` and `docs/getting-started.md`.
+- Load [references/playbooks.md](references/playbooks.md) and pick the closest playbook for the task.
+
+## Execution Protocol
+
+1. Verify package versions in `package.json` and lockfile before using any API surface.
+2. Locate entry points and registration flow (`src/App.tsx`, component modules, command handlers).
+3. Implement using only public exports from `@floegence/floe-webapp-core` (`/app`, `/ui`, `/layout`, `/icons`, root).
+4. Align `FloeComponent.id`, sidebar items, and command navigation targets.
+5. Keep styling on design tokens (`text-foreground`, `bg-card`, `border-border`, etc.).
+6. Run deterministic checks before finishing:
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test -- --run
+pnpm build
+```
+
+## Constraints
+
+- Solid.js only: do not use React hooks/patterns.
+- Use `class=` in JSX, not `className=`.
+- Do not import `@floegence/floe-webapp-core/src/...` internal paths.
+- Keep command navigation ids aligned with registered component ids.
+- Prefer Solid control flow in JSX (`<For>`, `<Show>`, `<Switch>/<Match>`).
+- If API behavior is unclear, inspect installed type declarations before guessing.
+
+## Failure Handling
+
+- If checks fail, report the exact failing command and first actionable error.
+- Fix root causes instead of adding compatibility shims for old code paths.
+- If task requires risky incompatible behavior change, stop and ask for confirmation.
+
+## Output Format
+
+1. Brief summary of intent and implementation.
+2. Changed files with behavior impact.
+3. Verification result for each executed command.

package/skills/floe-webapp/references/playbooks.md

@@ -0,0 +1,59 @@
+# Floe-Webapp Skill Playbooks
+
+Use this file after reading `../SKILL.md`.
+
+## Playbook A: Add Or Update A FloeComponent
+
+1. Find the registration list:
+
+```bash
+rg "const components|FloeComponent\\[]" src --hidden
+```
+
+2. Keep every component entry aligned:
+- Stable `id` string.
+- `sidebar` metadata (`order`, `renderIn`, `fullScreen`, optional `badge`).
+- `commands` targets using the same `id`.
+
+3. Validate shell wiring still renders through:
+- `FloeApp`
+- `ActivityAppsMain`
+
+## Playbook B: Add Command Navigation
+
+1. Search command contribution points:
+
+```bash
+rg "commands|useCommand|command" src --hidden
+```
+
+2. Ensure each command action targets a registered component id.
+3. Keep labels, ids, and sidebar destination consistent.
+
+## Playbook C: Implement UI With Public Exports
+
+Allowed imports:
+- `@floegence/floe-webapp-core`
+- `@floegence/floe-webapp-core/app`
+- `@floegence/floe-webapp-core/ui`
+- `@floegence/floe-webapp-core/layout`
+- `@floegence/floe-webapp-core/icons`
+
+Forbidden:
+- `@floegence/floe-webapp-core/src/...`
+
+## Playbook D: Verify And Diagnose
+
+Run:
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test -- --run
+pnpm build
+```
+
+If a command fails:
+1. Capture the first actionable error.
+2. Fix the nearest root cause.
+3. Re-run from the failed command onward.

package/templates/full/AGENTS.md

@@ -1,10 +1,22 @@
 # Floe-Webapp AI Coding Skill
 
-> Tool-agnostic framework guidance for AI coding tools (Claude Code, Codex, Cursor, Copilot, etc.)
+> Tool-agnostic framework guidance for AI coding tools
 > to generate maintainable floe-webapp applications.
 
 ---
 
+## 0. Open Agent Skill Package
+
+This template includes a portable skill package at:
+
+- `skills/floe-webapp/SKILL.md`
+- `skills/floe-webapp/references/playbooks.md`
+
+The `SKILL.md` format follows the open Agent Skills shape (frontmatter + structured sections).
+Agent runtimes may use different discovery paths, but this project stores the skill in a neutral location for reuse.
+
+---
+
 ## 1. Identity & Stack
 
 **Floe-Webapp** is a VSCode-style web application framework built on **Solid.js**.

package/templates/full/skills/floe-webapp/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: floe-webapp
+description: Implement, refactor, and debug Floe-Webapp Solid.js applications with @floegence/floe-webapp-core public exports. Use for FloeApp shell wiring, FloeComponent sidebar or command registration, lifecycle hooks, design-token-first styling, and build or typecheck failures in Floe-Webapp projects.
+---
+
+# Floe-Webapp Skill
+
+## Scope
+
+- Implement or refactor pages/components in a Floe-Webapp app.
+- Add or update `FloeComponent` registration (`sidebar`, `commands`, lifecycle hooks).
+- Diagnose framework-usage issues and local build/lint/typecheck/test failures.
+
+## Required Inputs
+
+- Read project-root `AGENTS.md` first when available.
+- If `AGENTS.md` is absent, read `README.md` and `docs/getting-started.md`.
+- Load [references/playbooks.md](references/playbooks.md) and pick the closest playbook for the task.
+
+## Execution Protocol
+
+1. Verify package versions in `package.json` and lockfile before using any API surface.
+2. Locate entry points and registration flow (`src/App.tsx`, component modules, command handlers).
+3. Implement using only public exports from `@floegence/floe-webapp-core` (`/app`, `/ui`, `/layout`, `/icons`, root).
+4. Align `FloeComponent.id`, sidebar items, and command navigation targets.
+5. Keep styling on design tokens (`text-foreground`, `bg-card`, `border-border`, etc.).
+6. Run deterministic checks before finishing:
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test -- --run
+pnpm build
+```
+
+## Constraints
+
+- Solid.js only: do not use React hooks/patterns.
+- Use `class=` in JSX, not `className=`.
+- Do not import `@floegence/floe-webapp-core/src/...` internal paths.
+- Keep command navigation ids aligned with registered component ids.
+- Prefer Solid control flow in JSX (`<For>`, `<Show>`, `<Switch>/<Match>`).
+- If API behavior is unclear, inspect installed type declarations before guessing.
+
+## Failure Handling
+
+- If checks fail, report the exact failing command and first actionable error.
+- Fix root causes instead of adding compatibility shims for old code paths.
+- If task requires risky incompatible behavior change, stop and ask for confirmation.
+
+## Output Format
+
+1. Brief summary of intent and implementation.
+2. Changed files with behavior impact.
+3. Verification result for each executed command.

package/templates/full/skills/floe-webapp/references/playbooks.md

@@ -0,0 +1,59 @@
+# Floe-Webapp Skill Playbooks
+
+Use this file after reading `../SKILL.md`.
+
+## Playbook A: Add Or Update A FloeComponent
+
+1. Find the registration list:
+
+```bash
+rg "const components|FloeComponent\\[]" src --hidden
+```
+
+2. Keep every component entry aligned:
+- Stable `id` string.
+- `sidebar` metadata (`order`, `renderIn`, `fullScreen`, optional `badge`).
+- `commands` targets using the same `id`.
+
+3. Validate shell wiring still renders through:
+- `FloeApp`
+- `ActivityAppsMain`
+
+## Playbook B: Add Command Navigation
+
+1. Search command contribution points:
+
+```bash
+rg "commands|useCommand|command" src --hidden
+```
+
+2. Ensure each command action targets a registered component id.
+3. Keep labels, ids, and sidebar destination consistent.
+
+## Playbook C: Implement UI With Public Exports
+
+Allowed imports:
+- `@floegence/floe-webapp-core`
+- `@floegence/floe-webapp-core/app`
+- `@floegence/floe-webapp-core/ui`
+- `@floegence/floe-webapp-core/layout`
+- `@floegence/floe-webapp-core/icons`
+
+Forbidden:
+- `@floegence/floe-webapp-core/src/...`
+
+## Playbook D: Verify And Diagnose
+
+Run:
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test -- --run
+pnpm build
+```
+
+If a command fails:
+1. Capture the first actionable error.
+2. Fix the nearest root cause.
+3. Re-run from the failed command onward.

package/templates/minimal/AGENTS.md

@@ -1,10 +1,22 @@
 # Floe-Webapp AI Coding Skill
 
-> Tool-agnostic framework guidance for AI coding tools (Claude Code, Codex, Cursor, Copilot, etc.)
+> Tool-agnostic framework guidance for AI coding tools
 > to generate maintainable floe-webapp applications.
 
 ---
 
+## 0. Open Agent Skill Package
+
+This template includes a portable skill package at:
+
+- `skills/floe-webapp/SKILL.md`
+- `skills/floe-webapp/references/playbooks.md`
+
+The `SKILL.md` format follows the open Agent Skills shape (frontmatter + structured sections).
+Agent runtimes may use different discovery paths, but this project stores the skill in a neutral location for reuse.
+
+---
+
 ## 1. Identity & Stack
 
 **Floe-Webapp** is a VSCode-style web application framework built on **Solid.js**.

package/templates/minimal/skills/floe-webapp/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: floe-webapp
+description: Implement, refactor, and debug Floe-Webapp Solid.js applications with @floegence/floe-webapp-core public exports. Use for FloeApp shell wiring, FloeComponent sidebar or command registration, lifecycle hooks, design-token-first styling, and build or typecheck failures in Floe-Webapp projects.
+---
+
+# Floe-Webapp Skill
+
+## Scope
+
+- Implement or refactor pages/components in a Floe-Webapp app.
+- Add or update `FloeComponent` registration (`sidebar`, `commands`, lifecycle hooks).
+- Diagnose framework-usage issues and local build/lint/typecheck/test failures.
+
+## Required Inputs
+
+- Read project-root `AGENTS.md` first when available.
+- If `AGENTS.md` is absent, read `README.md` and `docs/getting-started.md`.
+- Load [references/playbooks.md](references/playbooks.md) and pick the closest playbook for the task.
+
+## Execution Protocol
+
+1. Verify package versions in `package.json` and lockfile before using any API surface.
+2. Locate entry points and registration flow (`src/App.tsx`, component modules, command handlers).
+3. Implement using only public exports from `@floegence/floe-webapp-core` (`/app`, `/ui`, `/layout`, `/icons`, root).
+4. Align `FloeComponent.id`, sidebar items, and command navigation targets.
+5. Keep styling on design tokens (`text-foreground`, `bg-card`, `border-border`, etc.).
+6. Run deterministic checks before finishing:
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test -- --run
+pnpm build
+```
+
+## Constraints
+
+- Solid.js only: do not use React hooks/patterns.
+- Use `class=` in JSX, not `className=`.
+- Do not import `@floegence/floe-webapp-core/src/...` internal paths.
+- Keep command navigation ids aligned with registered component ids.
+- Prefer Solid control flow in JSX (`<For>`, `<Show>`, `<Switch>/<Match>`).
+- If API behavior is unclear, inspect installed type declarations before guessing.
+
+## Failure Handling
+
+- If checks fail, report the exact failing command and first actionable error.
+- Fix root causes instead of adding compatibility shims for old code paths.
+- If task requires risky incompatible behavior change, stop and ask for confirmation.
+
+## Output Format
+
+1. Brief summary of intent and implementation.
+2. Changed files with behavior impact.
+3. Verification result for each executed command.

package/templates/minimal/skills/floe-webapp/references/playbooks.md

@@ -0,0 +1,59 @@
+# Floe-Webapp Skill Playbooks
+
+Use this file after reading `../SKILL.md`.
+
+## Playbook A: Add Or Update A FloeComponent
+
+1. Find the registration list:
+
+```bash
+rg "const components|FloeComponent\\[]" src --hidden
+```
+
+2. Keep every component entry aligned:
+- Stable `id` string.
+- `sidebar` metadata (`order`, `renderIn`, `fullScreen`, optional `badge`).
+- `commands` targets using the same `id`.
+
+3. Validate shell wiring still renders through:
+- `FloeApp`
+- `ActivityAppsMain`
+
+## Playbook B: Add Command Navigation
+
+1. Search command contribution points:
+
+```bash
+rg "commands|useCommand|command" src --hidden
+```
+
+2. Ensure each command action targets a registered component id.
+3. Keep labels, ids, and sidebar destination consistent.
+
+## Playbook C: Implement UI With Public Exports
+
+Allowed imports:
+- `@floegence/floe-webapp-core`
+- `@floegence/floe-webapp-core/app`
+- `@floegence/floe-webapp-core/ui`
+- `@floegence/floe-webapp-core/layout`
+- `@floegence/floe-webapp-core/icons`
+
+Forbidden:
+- `@floegence/floe-webapp-core/src/...`
+
+## Playbook D: Verify And Diagnose
+
+Run:
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test -- --run
+pnpm build
+```
+
+If a command fails:
+1. Capture the first actionable error.
+2. Fix the nearest root cause.
+3. Re-run from the failed command onward.

package/templates/full/_claude/commands/floe-webapp.md

@@ -1,24 +0,0 @@
-# Floe-Webapp Coding Skill
-
-Load the floe-webapp coding skill and apply it to implementation tasks.
-
-## Instructions
-
-1. Read `AGENTS.md` at the project root first.
-2. Treat `AGENTS.md` as tool-agnostic framework guidance.
-3. Use the current project's `package.json`/lockfile as the version source of truth.
-4. Follow hard constraints first:
-   - Solid.js patterns (not React)
-   - public subpath imports only
-   - design-token-first styling
-5. Then apply the recommended coding priorities in `AGENTS.md`.
-
-## Quick Start
-
-When implementing a floe-webapp feature:
-
-1. Read `AGENTS.md`.
-2. Build with `@floegence/floe-webapp-core` public exports (`/app`, `/ui`, `/layout`, `/icons`, root).
-3. Register features as `FloeComponent` and align `sidebar` + `commands` behavior.
-4. Keep styles token-based (`text-foreground`, `bg-card`, `border-border`, etc.).
-5. Validate API usage against installed dependency versions.

package/templates/minimal/_claude/commands/floe-webapp.md

@@ -1,24 +0,0 @@
-# Floe-Webapp Coding Skill
-
-Load the floe-webapp coding skill and apply it to implementation tasks.
-
-## Instructions
-
-1. Read `AGENTS.md` at the project root first.
-2. Treat `AGENTS.md` as tool-agnostic framework guidance.
-3. Use the current project's `package.json`/lockfile as the version source of truth.
-4. Follow hard constraints first:
-   - Solid.js patterns (not React)
-   - public subpath imports only
-   - design-token-first styling
-5. Then apply the recommended coding priorities in `AGENTS.md`.
-
-## Quick Start
-
-When implementing a floe-webapp feature:
-
-1. Read `AGENTS.md`.
-2. Build with `@floegence/floe-webapp-core` public exports (`/app`, `/ui`, `/layout`, `/icons`, root).
-3. Register features as `FloeComponent` and align `sidebar` + `commands` behavior.
-4. Keep styles token-based (`text-foreground`, `bg-card`, `border-border`, etc.).
-5. Validate API usage against installed dependency versions.