@cmssy/cli 0.12.1 → 0.14.0

package/dist/commands/skills.js

@@ -0,0 +1,178 @@
+import chalk from "chalk";
+import fs from "fs-extra";
+import inquirer from "inquirer";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const SKILLS_ROOT = path.resolve(__dirname, "../skills");
+const EDITOR_TARGETS = ["claude"];
+const SKILLS = {
+    block: {
+        name: "block",
+        label: "Block dev (CLI + defineBlock/defineTemplate workflow)",
+        sourceBasename: "cmssy-block.md",
+        destDir: "cmssy-block",
+        examplePrompt: "scaffold a pricing block and publish as patch",
+    },
+    "mcp-content": {
+        name: "mcp-content",
+        label: "Content editing via @cmssy/mcp-server",
+        sourceBasename: "cmssy-mcp-content.md",
+        destDir: "cmssy-mcp-content",
+        examplePrompt: "add a new testimonials block to the homepage, in English and Polish",
+    },
+};
+function resolveEditorTarget(raw) {
+    const target = (raw ?? "claude").trim().toLowerCase();
+    if (!EDITOR_TARGETS.includes(target)) {
+        // JSON.stringify so whitespace-only / empty raw input is visible in
+        // the error (otherwise interpolating `"  "` gives a blank message).
+        console.error(chalk.red(`✖ Unknown editor target: raw=${JSON.stringify(raw)}, normalized=${JSON.stringify(target)}`) + chalk.gray(`\n  Supported: ${EDITOR_TARGETS.join(", ")}`));
+        process.exit(1);
+    }
+    return target;
+}
+function resolveSourcePath(editor, skill) {
+    return path.join(SKILLS_ROOT, editor, skill.sourceBasename);
+}
+function resolveInstallDir(editor, skill, opts) {
+    // Editor-specific layout. Today only `claude`, whose layout is:
+    //   ~/.claude/skills/<destDir>/SKILL.md   (global)
+    //   <cwd>/.claude/skills/<destDir>/SKILL.md  (local)
+    if (editor === "claude") {
+        const root = opts.local ? opts.cwd : os.homedir();
+        return path.join(root, ".claude", "skills", skill.destDir);
+    }
+    // Fallback (unreachable today, keeps TS happy for future targets)
+    throw new Error(`Unsupported editor target: ${editor}`);
+}
+function postInstallHint(editor, skill, installPath) {
+    if (editor === "claude") {
+        return [
+            chalk.gray("Next step:"),
+            chalk.white("  Restart Claude Code (or open a new session) so it picks up the skill."),
+            chalk.gray("  Then try something like:"),
+            chalk.white(`    "${skill.examplePrompt}"`),
+            "",
+            chalk.gray(`Installed at: ${installPath}`),
+        ].join("\n");
+    }
+    return chalk.gray(`Installed at: ${installPath}`);
+}
+async function installOne(skill, editor, options) {
+    const sourcePath = resolveSourcePath(editor, skill);
+    if (!(await fs.pathExists(sourcePath))) {
+        console.error(chalk.red(`✖ Skill source missing: ${sourcePath}`) +
+            chalk.gray("\n  This is a packaging bug - please report it at https://github.com/cmssy-io/cmssy-cli/issues"));
+        process.exit(1);
+    }
+    const installDir = resolveInstallDir(editor, skill, {
+        local: !!options.local,
+        cwd: process.cwd(),
+    });
+    const installPath = path.join(installDir, "SKILL.md");
+    const exists = await fs.pathExists(installPath);
+    if (exists && !options.force) {
+        if (options.yes) {
+            console.error(chalk.red(`✖ ${installPath} already exists`) +
+                chalk.gray("\n  Pass --force to overwrite."));
+            process.exit(1);
+        }
+        const { overwrite } = await inquirer.prompt([
+            {
+                type: "confirm",
+                name: "overwrite",
+                message: `${installPath} already exists. Overwrite?`,
+                default: false,
+            },
+        ]);
+        if (!overwrite) {
+            console.log(chalk.yellow(`⚠ Skipped ${skill.name} - ${installPath} unchanged.`));
+            return "skipped";
+        }
+    }
+    await fs.ensureDir(installDir);
+    await fs.copy(sourcePath, installPath, { overwrite: true });
+    const scope = options.local ? "local (.claude/)" : "global (~/.claude/)";
+    console.log(chalk.green(`✔ Installed ${skill.label} skill`) + chalk.gray(` → ${scope}`));
+    console.log();
+    console.log(postInstallHint(editor, skill, installPath));
+    console.log();
+    return "installed";
+}
+export async function skillsInstallCommand(rawSkill, options) {
+    const editor = resolveEditorTarget(options.target);
+    // Normalize once - whitespace-only or empty input is treated as "no skill"
+    // so `cmssy skills install "   "` behaves like `cmssy skills install`.
+    const skill = rawSkill?.trim().toLowerCase() || undefined;
+    // Friendly error if user passes an editor name where a skill name is expected
+    // (covers the pre-0.14.0 `cmssy skills install claude` shape).
+    if (skill && EDITOR_TARGETS.includes(skill)) {
+        console.error(chalk.red(`✖ "${rawSkill}" is an editor target, not a skill name.`) +
+            chalk.gray(`\n  The first positional argument is now the skill name (e.g. "block", "mcp-content").`) +
+            chalk.gray(`\n  Pass editor with --target, e.g.: cmssy skills install block --target ${skill}`));
+        process.exit(1);
+    }
+    if (options.all) {
+        if (skill) {
+            console.error(chalk.red(`✖ Cannot combine --all with a skill name.`) +
+                chalk.gray("\n  Either pass a skill name or use --all, not both."));
+            process.exit(1);
+        }
+        for (const entry of Object.values(SKILLS)) {
+            await installOne(entry, editor, options);
+        }
+        return;
+    }
+    let skillName;
+    if (skill) {
+        if (!Object.hasOwn(SKILLS, skill)) {
+            console.error(chalk.red(`✖ Unknown skill: ${rawSkill}`) +
+                chalk.gray(`\n  Available skills: ${Object.keys(SKILLS).join(", ")}`) +
+                chalk.gray(`\n  Run 'cmssy skills list' to see all skills.`));
+            process.exit(1);
+        }
+        skillName = skill;
+    }
+    else {
+        // No skill passed (or whitespace-only) → interactive prompt (unless -y)
+        if (options.yes) {
+            console.error(chalk.red(`✖ No skill specified.`) +
+                chalk.gray(`\n  Pass a skill name (e.g. 'block', 'mcp-content') or use --all.`) +
+                chalk.gray(`\n  Run 'cmssy skills list' to see all skills.`));
+            process.exit(1);
+        }
+        const { chosen } = await inquirer.prompt([
+            {
+                type: "list",
+                name: "chosen",
+                message: "Which skill to install?",
+                choices: Object.values(SKILLS).map((s) => ({
+                    name: `${s.name} - ${s.label}`,
+                    value: s.name,
+                })),
+            },
+        ]);
+        skillName = chosen;
+    }
+    await installOne(SKILLS[skillName], editor, options);
+}
+export function skillsListCommand() {
+    console.log();
+    console.log(chalk.bold("Available skills:"));
+    console.log();
+    const padName = Math.max(...Object.values(SKILLS).map((s) => s.name.length));
+    for (const skill of Object.values(SKILLS)) {
+        console.log(`  ${chalk.cyan(skill.name.padEnd(padName))}  ${skill.label}`);
+    }
+    console.log();
+    console.log(chalk.gray(`Supported editor targets: ${EDITOR_TARGETS.join(", ")}`));
+    console.log();
+    console.log(chalk.gray("Install with:"));
+    console.log(chalk.white("  cmssy skills install <skill>"));
+    console.log(chalk.white("  cmssy skills install --all"));
+    console.log();
+}
+//# sourceMappingURL=skills.js.map

package/dist/commands/skills.js.map

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

package/dist/skills/claude/cmssy-block.md

@@ -0,0 +1,345 @@
+---
+name: cmssy-block
+description: "Run the full cmssy CLI lifecycle - init, link, scaffold/edit blocks and templates, dev/build/test, publish, sync. Trigger when the user asks to: initialize a cmssy project, link to a workspace, create/add a new block or template, add a field to a block's schema, edit config.ts, run cmssy dev/build/test/doctor, publish a block, bump a block version, sync a block from the design library, or work with defineBlock/defineTemplate. Trigger on words: cmssy, blok, block, template, publish, opublikuj, workspace, link, sync, defineBlock, defineTemplate, scaffold, zescafoldwac."
+---
+
+# cmssy-block
+
+Operates the full cmssy CLI workflow for blocks and templates in a project like `cmssy-marketing`. Covers every command the CLI exposes: `init`, `link`, `create`, `dev`, `test`, `build`, `publish`, `sync`, `doctor`, `workspaces`.
+
+## 0. Orientation
+
+```bash
+cmssy --version            # CLI must be installed globally
+cmssy doctor               # all-in-one health check
+```
+
+`cmssy doctor` is the canonical precheck. It verifies:
+- Node >= 18, npm, Next.js, React versions
+- `cmssy.config.js` exists
+- `.env` with `CMSSY_API_URL`, `CMSSY_API_TOKEN`, `CMSSY_WORKSPACE_ID`
+- API reachable, token valid, workspace accessible
+
+Run it before any non-trivial operation. If something fails, fix that first - don't proceed.
+
+The project uses **pnpm**. Never run `npm install` - use `pnpm install`, `pnpm typecheck`, `pnpm lint`.
+
+## 1. Project lifecycle (in order)
+
+### 1.1 `cmssy init` - start a new project or bolt onto an existing one
+
+```bash
+cmssy init <name>          # creates ./<name> via create-next-app + cmssy scaffolding
+cmssy init -y <name>       # skip prompts, use defaults
+cmssy init                 # add cmssy to the current Next.js project
+```
+
+Outputs: `cmssy.config.js`, `blocks/`, `templates/`, `styles/main.css`, `components/`, example block.
+
+### 1.2 `cmssy link` - connect the project to a workspace
+
+```bash
+cmssy link                                       # interactive: pick workspace, paste token
+cmssy link --token cs_xxx --workspace <id|slug>  # non-interactive, for CI or scripted setup
+cmssy link --api-url https://api.cmssy.io/graphql
+```
+
+Writes credentials and `CMSSY_WORKSPACE_ID` to `.env`. Tokens come from https://cmssy.io/settings/tokens. List existing workspaces with `cmssy workspaces`.
+
+### 1.3 `cmssy workspaces` - show what this machine can publish to
+
+```bash
+cmssy workspaces
+```
+
+Returns name, slug, ID, and role for every accessible workspace. Use this when the user is ambiguous about the publish target.
+
+### 1.4 `cmssy create` - scaffold blocks or templates
+
+```bash
+cmssy create block <kebab-name> [-d "desc"] [-c <category>] [-t "tag1,tag2"] [-y]
+cmssy create template <kebab-name> [-d "desc"] [-y]
+```
+
+Categories: `marketing`, `typography`, `media`, `layout`, `forms`, `navigation`, `other`.
+
+Always use `-y` in automated flows unless the user wants to be prompted.
+
+### 1.5 `cmssy dev` - local preview with HMR
+
+```bash
+cmssy dev              # port 3000
+cmssy dev -p 8080      # custom port
+```
+
+Watches `config.ts` and auto-regenerates `block.d.ts`. Use for visual verification after edits.
+
+### 1.6 `cmssy test` - vitest runner
+
+```bash
+cmssy test                       # all blocks/templates
+cmssy test --block hero faq      # subset
+cmssy test --watch
+cmssy test --coverage
+```
+
+Test files live at `blocks/*/src/**/*.{test,spec}.{ts,tsx}` (same for templates). If no tests exist yet, this is a no-op.
+
+### 1.7 `cmssy build` - production bundle
+
+```bash
+cmssy build                              # everything
+cmssy build --block hero pricing         # subset
+cmssy build --framework react            # override
+```
+
+Outputs `public/@<vendor>/blocks.<name>/<version>/{index.js,index.css,package.json}`. Run before publish if you want to preview the bundle.
+
+### 1.8 `cmssy publish` - upload to workspace
+
+```bash
+cmssy publish <name> --patch                      # single, patch bump
+cmssy publish --all --patch                       # everything
+cmssy publish <name> -w <workspaceId> --patch     # explicit workspace (otherwise .env)
+cmssy publish <name> --patch --dry-run            # preview only, upload nothing
+cmssy publish <name> --patch --with-source        # include source for AI Block Builder
+cmssy publish <name> --patch --zip                # package and upload ZIP instead of GraphQL
+```
+
+**Exactly one bump flag:** `--patch` | `--minor` | `--major` | `--no-bump`.
+
+**Bump semantics:**
+- `--patch` - bug fix, copy tweak, style-only change. No schema change.
+- `--minor` - added optional fields, new variants. Non-breaking schema additions.
+- `--major` - renamed/removed fields, changed field types, breaking component contract.
+
+**Content preservation:** republishing preserves `defaultContent` and `schemaFields` on the workspace by default. Pass `--overwrite-content` only when the user explicitly wants to reset them from `config.ts` / `preview.json`.
+
+**Breaking changes** trigger a confirmation prompt; pass `--force` only with explicit user approval.
+
+### 1.9 `cmssy sync` - pull blocks down from a workspace
+
+```bash
+cmssy sync @cmssy/blocks.hero                    # one package from the design library
+cmssy sync --workspace <id>                      # everything from a workspace
+```
+
+Use when cloning a project's block set to a new repo, or when a block has drifted from its published version.
+
+## 2. Block anatomy (non-negotiable)
+
+Every block lives in `blocks/<kebab-name>/`:
+
+```
+blocks/<name>/
+├── config.ts          # defineBlock({ name, description, category, tags, schema })
+├── package.json       # { "name": "@<project>/blocks.<name>", "version": "x.y.z" }
+├── preview.json       # sample content for cmssy dev
+└── src/
+    ├── index.tsx      # export { default } from "./<Pascal>"; import "./index.css";
+    ├── <Pascal>.tsx   # the React component
+    ├── index.css      # @import "../../../styles/main.css";
+    └── block.d.ts     # AUTO-GENERATED from config.ts - never hand-edit
+```
+
+**Naming (hard rules):**
+- Directory + package `name` suffix: `kebab-case` (`blog-post-hero`).
+- Component file and default export: `PascalCase` matching the directory (`BlogPostHero.tsx`).
+- Package name: `@<projectName>/blocks.<kebab-name>` where `projectName` comes from `cmssy.config.js`.
+- New blocks start at `"version": "1.0.0"`.
+
+## 3. Writing `config.ts`
+
+Import from `@cmssy/cli/config`. Available field types:
+
+| type | Use for |
+| --- | --- |
+| `singleLine` | Short text (heading, label, badge). |
+| `multiLine` | Paragraph without formatting. |
+| `richText` | HTML body copy. |
+| `link` | URL. |
+| `media` | Image or video (returns URL string). |
+| `boolean` | Toggle. |
+| `numeric` | Number. |
+| `date` | ISO date string. |
+| `color` | Hex color picker. |
+| `select` | Enum with `options: [{ label, value }]`. |
+| `repeater` | Array of sub-objects with nested `schema`. |
+| `form` | Reference to a form-builder form. |
+| `pageSelector` | Pick a page from the workspace. |
+
+**Field options:** `label` (required), `defaultValue`, `placeholder`, `required`, `group` (groups fields in the editor UI).
+
+```ts
+import { defineBlock, field } from "@cmssy/cli/config";
+
+export default defineBlock({
+  name: "Feature Grid",
+  description: "Grid of feature cards with icon, title, description",
+  category: "marketing",
+  tags: ["marketing", "features", "grid"],
+
+  schema: {
+    heading: field({ type: "singleLine", label: "Heading", required: true }),
+    headingHighlight: field({ type: "singleLine", label: "Highlight" }),
+    description: field({ type: "multiLine", label: "Description" }),
+    features: field({
+      type: "repeater",
+      label: "Features",
+      schema: {
+        title: field({ type: "singleLine", label: "Title", required: true }),
+        description: field({ type: "multiLine", label: "Description" }),
+        icon: field({
+          type: "select",
+          label: "Icon",
+          options: [
+            { label: "Zap", value: "ZapIcon" },
+            { label: "Sparkles", value: "SparklesIcon" },
+          ],
+        }),
+        color: field({ type: "color", label: "Accent color" }),
+      },
+    }),
+  },
+});
+```
+
+After editing `config.ts`, `block.d.ts` regenerates on the next `cmssy dev` or `cmssy build`. Never hand-edit it.
+
+## 4. Writing the component
+
+Follow the design system in the repo's `DESIGN.md`:
+
+- Import `Container` from `../../../components/container`.
+- Section wrapper: `<section className="py-24">` or `"py-24 bg-slate-50/50 dark:bg-slate-900/50"` for alternating tint.
+- Destructure `content` with defaults: `const { heading = "Default" } = content;`.
+- Gradient-clip highlight phrases: `bg-linear-to-r from-violet-600 to-purple-600 bg-clip-text text-transparent`.
+- Primary CTAs: gradient pill button with `shadow-lg shadow-violet-500/25`. Secondary: outline with `border-input`.
+- Icons: `lucide-react`, default stroke width.
+- Rich text: `dangerouslySetInnerHTML` inside a `prose` wrapper.
+
+```tsx
+import { Container } from "../../../components/container";
+import { BlockContent } from "./block";
+
+export default function FeatureGrid({ content }: { content: BlockContent }) {
+  const { heading = "", features = [] } = content;
+  return (
+    <section className="py-24">
+      <Container>{/* ... */}</Container>
+    </section>
+  );
+}
+```
+
+Blocks that read platform data (auth, i18n) accept a second prop:
+
+```tsx
+export default function Header({ content, context }: {
+  content: BlockContent;
+  context?: PlatformContext;
+}) { ... }
+```
+
+Components that use hooks or browser APIs: `"use client";` at the top.
+
+## 5. `preview.json`
+
+Sample content for `cmssy dev`. Keys must match `config.ts` field names. Repeater fields take arrays of objects. Make it realistic - preview is what reviewers see.
+
+## 6. Templates
+
+```
+templates/<name>/
+├── config.ts        # defineTemplate({ name, description, category, tags, pages })
+├── package.json
+├── pages.json       # layoutPositions (header/footer) + block references
+├── preview.json
+└── src/             # optional root component
+```
+
+```ts
+import { defineTemplate, field } from "@cmssy/cli/config";
+
+export default defineTemplate({
+  name: "Marketing Site",
+  description: "...",
+  category: "website",
+  tags: [...],
+  pages: [
+    {
+      name: "Home",
+      slug: "/",
+      blocks: [
+        { type: "hero", content: { heading: "...", ... } },
+        { type: "features", content: { ... } },
+      ],
+    },
+  ],
+});
+```
+
+Publish templates the same way as blocks: `cmssy publish <template-name> --patch`.
+
+## 7. Standard workflows
+
+### Brand-new project
+
+```bash
+cmssy init my-blocks -y
+cd my-blocks
+cmssy link                 # interactive - pick workspace
+cmssy doctor               # confirm green
+cmssy dev
+```
+
+### Add a new block end-to-end
+
+```bash
+cmssy create block testimonials -c marketing -t "marketing,social-proof" -y
+# edit blocks/testimonials/config.ts, Testimonials.tsx, preview.json
+cmssy dev                                  # visual check
+pnpm typecheck && pnpm lint
+cmssy test --block testimonials            # if tests exist
+cmssy publish testimonials --patch --dry-run
+cmssy publish testimonials --patch
+```
+
+### Extend an existing block with an optional field
+
+1. Add `field({...})` to `config.ts`. Don't set `required: true` - that's breaking.
+2. Update the component to read and render it with a default.
+3. Update `preview.json`.
+4. `cmssy publish <block> --minor`.
+
+### Copy-only fix
+
+1. Edit default strings or JSX in the component.
+2. `cmssy publish <block> --patch`.
+
+### Pull a block from the design library
+
+```bash
+cmssy sync @cmssy/blocks.hero
+```
+
+## 8. Safety rules (always)
+
+- Run `cmssy doctor` before publishing.
+- Never fabricate a workspace ID. Use `cmssy workspaces` and confirm with the user.
+- Never pass `--force` without explicit user approval (skips breaking-change confirmation).
+- Never pass `--overwrite-content` without explicit user approval (wipes editor content).
+- Use `--dry-run` first when unsure what will change.
+- Confirm with the user before publishing from a branch other than `develop` or `main`.
+- Commit local changes before publishing - publish uploads the working tree.
+- For init and link, never write a token or workspace ID into `.env` without user confirmation.
+
+## 9. Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `doctor` says token invalid | Revoked/expired token | `cmssy link` again with a fresh token from https://cmssy.io/settings/tokens |
+| Publish says "workspace not accessible" | Wrong `CMSSY_WORKSPACE_ID` or no role | `cmssy workspaces`, update `.env` |
+| Schema diff prompts blocking publish | Breaking field change | Bump `--major`, or revert to non-breaking, or `--force` with user approval |
+| `block.d.ts` shows wrong fields | Stale generation | Restart `cmssy dev`, or run `cmssy build` to regenerate |
+| Dev server shows a blank block | `preview.json` missing keys | Match keys to `config.ts` field names |