@supatent/skills 0.1.0

package/bin/install.mjs

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+
+// bin/install.mjs - Self-contained zero-dependency installer for @supatent/skills
+// Copies bundled skill files to .claude/skills/supatent/ with manifest tracking.
+
+import { readFile, writeFile, mkdir, copyFile, readdir, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { join, dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline/promises';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const SKILLS_SOURCE_DIR = join(__dirname, '..', 'skills');
+const TARGET_SUBDIR = join('.claude', 'skills', 'supatent');
+
+// ---------------------------------------------------------------------------
+// Exported helpers (for testability)
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute SHA256 hex digest of a file.
+ */
+export async function sha256(filePath) {
+  const content = await readFile(filePath);
+  return createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Async generator that recursively yields all file paths under `dir`.
+ */
+export async function* walkDir(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkDir(fullPath);
+    } else {
+      yield fullPath;
+    }
+  }
+}
+
+/**
+ * Prompt user for confirmation. Returns true if confirmed.
+ * Auto-confirms when `force` is true or stdin is not a TTY.
+ */
+export async function confirm(message, { force = false } = {}) {
+  if (force || !process.stdin.isTTY) return true;
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    const answer = await rl.question(`${message} [y/N] `);
+    return answer.trim().toLowerCase() === 'y';
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Read and parse .manifest.json. Returns null if missing or invalid.
+ */
+export async function readManifest(manifestPath) {
+  try {
+    const raw = await readFile(manifestPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && parsed.files) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Walk source directory and build a map of { relativePath: { sourcePath, checksum } }.
+ * Relative paths use forward slashes for cross-platform consistency.
+ */
+export async function buildSourceMap(sourceDir) {
+  const sourceMap = {};
+  for await (const filePath of walkDir(sourceDir)) {
+    const relPath = relative(sourceDir, filePath).split(join('a', 'b').charAt(1)).join('/');
+    const checksum = await sha256(filePath);
+    sourceMap[relPath] = { sourcePath: filePath, checksum };
+  }
+  return sourceMap;
+}
+
+/**
+ * Compute diff between source files, existing manifest, and installed files.
+ * Returns { newFiles, changed, unchanged, userModified }.
+ *
+ * - newFiles: files not in manifest (fresh)
+ * - changed: source checksum differs from manifest, installed file matches manifest (safe to overwrite)
+ * - unchanged: source checksum matches manifest
+ * - userModified: installed file differs from BOTH manifest AND source (user edited it, and source also changed)
+ */
+export async function computeDiff(sourceMap, manifest, targetDir) {
+  const result = {
+    newFiles: [],     // relative paths
+    changed: [],      // relative paths
+    unchanged: [],    // relative paths
+    userModified: [], // relative paths (source changed AND user edited installed copy)
+  };
+
+  const manifestFiles = manifest ? manifest.files : {};
+
+  for (const [relPath, { checksum: sourceChecksum }] of Object.entries(sourceMap)) {
+    const manifestChecksum = manifestFiles[relPath];
+
+    if (!manifestChecksum) {
+      // Not in manifest -- new file
+      result.newFiles.push(relPath);
+      continue;
+    }
+
+    if (sourceChecksum === manifestChecksum) {
+      // Source hasn't changed since last install
+      result.unchanged.push(relPath);
+      continue;
+    }
+
+    // Source has changed. Check if the installed file was user-modified.
+    const installedPath = join(targetDir, relPath);
+    let installedChecksum = null;
+    try {
+      installedChecksum = await sha256(installedPath);
+    } catch {
+      // Installed file missing -- treat as changed (needs re-copy)
+      result.changed.push(relPath);
+      continue;
+    }
+
+    if (installedChecksum === manifestChecksum) {
+      // Installed file matches manifest -- user hasn't touched it, safe to overwrite
+      result.changed.push(relPath);
+    } else {
+      // Installed file differs from manifest AND source changed -- user modified
+      result.userModified.push(relPath);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Read version from package.json relative to bin/.
+ */
+export async function getVersion() {
+  const pkgPath = join(__dirname, '..', 'package.json');
+  const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+  return pkg.version;
+}
+
+// ---------------------------------------------------------------------------
+// Main installer flow
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const args = process.argv.slice(2);
+  const force = args.includes('--force');
+
+  const version = await getVersion();
+  const cwd = process.cwd();
+  const claudeDir = join(cwd, '.claude');
+  const targetDir = join(cwd, TARGET_SUBDIR);
+  const manifestPath = join(targetDir, '.manifest.json');
+
+  // -----------------------------------------------------------------------
+  // Step a: Check .claude/ directory
+  // -----------------------------------------------------------------------
+  let claudeExists = false;
+  try {
+    const s = await stat(claudeDir);
+    claudeExists = s.isDirectory();
+  } catch {
+    // does not exist
+  }
+
+  if (!claudeExists) {
+    console.log('\x1b[33m!\x1b[0m No .claude/ directory found. This installer creates skill files for Claude Code.');
+    const ok = await confirm('Create .claude/ directory and continue?', { force });
+    if (!ok) {
+      console.log('Aborted.');
+      process.exitCode = 1;
+      return;
+    }
+    await mkdir(claudeDir, { recursive: true });
+  }
+
+  // -----------------------------------------------------------------------
+  // Step b: Walk source skills/ directory and build source map
+  // -----------------------------------------------------------------------
+  const sourceMap = await buildSourceMap(SKILLS_SOURCE_DIR);
+  const sourceFiles = Object.keys(sourceMap);
+
+  // -----------------------------------------------------------------------
+  // Step c: Read existing manifest
+  // -----------------------------------------------------------------------
+  const manifest = await readManifest(manifestPath);
+
+  // -----------------------------------------------------------------------
+  // Step d: Compute diff
+  // -----------------------------------------------------------------------
+  const diff = await computeDiff(sourceMap, manifest, targetDir);
+
+  // -----------------------------------------------------------------------
+  // Step e: Handle user-modified files
+  // -----------------------------------------------------------------------
+  const filesToCopy = [...diff.newFiles, ...diff.changed];
+  const skippedFiles = [];
+
+  for (const relPath of diff.userModified) {
+    const ok = await confirm(`File ${relPath} has been manually modified. Overwrite?`, { force });
+    if (ok) {
+      filesToCopy.push(relPath);
+    } else {
+      skippedFiles.push(relPath);
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Check if anything to do
+  // -----------------------------------------------------------------------
+  if (filesToCopy.length === 0 && skippedFiles.length === 0) {
+    console.log(`\x1b[32m\u2713\x1b[0m Already up to date (v${version})`);
+    console.log('');
+    console.log('  Run \x1b[36m/supatent:core\x1b[0m to get started');
+    return;
+  }
+
+  // -----------------------------------------------------------------------
+  // Step f: Copy files
+  // -----------------------------------------------------------------------
+  const isFreshInstall = !manifest;
+
+  for (const relPath of filesToCopy) {
+    const source = sourceMap[relPath].sourcePath;
+    const target = join(targetDir, relPath);
+    await mkdir(dirname(target), { recursive: true });
+    await copyFile(source, target);
+
+    if (isFreshInstall) {
+      console.log(`  \x1b[36m\u2192\x1b[0m ${relPath}`);
+    } else if (diff.newFiles.includes(relPath)) {
+      console.log(`  \x1b[32m+\x1b[0m Added ${relPath}`);
+    } else {
+      console.log(`  \x1b[33m\u2191\x1b[0m Updated ${relPath}`);
+    }
+  }
+
+  for (const relPath of skippedFiles) {
+    console.log(`  \x1b[90m-\x1b[0m Skipped ${relPath} (user modified)`);
+  }
+
+  // -----------------------------------------------------------------------
+  // Step g: Write manifest
+  // -----------------------------------------------------------------------
+  const manifestFiles = {};
+
+  // Retain old manifest entries for skipped files
+  if (manifest && manifest.files) {
+    for (const relPath of skippedFiles) {
+      if (manifest.files[relPath]) {
+        manifestFiles[relPath] = manifest.files[relPath];
+      }
+    }
+  }
+
+  // Add/update entries for all source files (except skipped, which keep old entry)
+  for (const relPath of sourceFiles) {
+    if (!skippedFiles.includes(relPath)) {
+      manifestFiles[relPath] = sourceMap[relPath].checksum;
+    }
+  }
+
+  const manifestData = {
+    version,
+    installedAt: new Date().toISOString(),
+    files: manifestFiles,
+  };
+
+  await mkdir(dirname(manifestPath), { recursive: true });
+  await writeFile(manifestPath, JSON.stringify(manifestData, null, 2) + '\n');
+
+  // -----------------------------------------------------------------------
+  // Step h: Print summary
+  // -----------------------------------------------------------------------
+  console.log('');
+  if (isFreshInstall) {
+    console.log(`\x1b[32m\u2713\x1b[0m Installed ${filesToCopy.length} files to ${TARGET_SUBDIR}/ (v${version})`);
+  } else {
+    console.log(`\x1b[32m\u2713\x1b[0m Updated ${filesToCopy.length} file${filesToCopy.length === 1 ? '' : 's'} in ${TARGET_SUBDIR}/ (v${version})`);
+  }
+  console.log('');
+  console.log('  Run \x1b[36m/supatent:core\x1b[0m to get started');
+}
+
+// ---------------------------------------------------------------------------
+// Run main only when executed directly (not when imported for testing)
+// ---------------------------------------------------------------------------
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === resolve(__filename);
+
+if (isMain) {
+  main().catch((err) => {
+    console.error(`\x1b[31mError:\x1b[0m ${err.message}`);
+    process.exitCode = 1;
+  });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@supatent/skills",
+  "version": "0.1.0",
+  "description": "Claude Code content authoring skills for Supatent CMS",
+  "type": "module",
+  "bin": {
+    "supatent-skills": "bin/install.mjs"
+  },
+  "files": [
+    "bin",
+    "skills"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "lint": "eslint bin/"
+  },
+  "devDependencies": {
+    "eslint": "^9.16.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "supatent",
+    "cms",
+    "claude-code",
+    "skills",
+    "content-authoring"
+  ],
+  "license": "MIT",
+  "author": "Supatent <hello@supatent.ai>",
+  "homepage": "https://supatent.ai/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/supatent/supatent.git",
+    "directory": "packages/skills"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/skills/content-blog/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: "supatent:content-blog"
+description: "Use when the user wants to create blog posts, update blog content, manage blog locales, fix blog SEO, or work with blog schemas (blog-post, blog-author, blog-settings)."
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Supatent Blog Content Skill
+
+You are a blog content assistant for Supatent CMS. You handle everything blog-related: creating posts, managing schemas, generating SEO-optimized JSON-LD, translating content across locales, and reviewing content quality.
+
+You are an intelligent assistant, not a form wizard. Read context, adapt to what exists, and only ask what you do not know. Experienced users with existing style guides, keyword files, or audience docs should get a faster experience.
+
+## Reference Files
+
+Load these files on-demand, not upfront. Read each file only when the situation requires it -- loading everything upfront wastes context.
+
+| File | When to Read |
+|------|-------------|
+| `./blog-sections.md` | Creating or modifying blog schemas -- contains full JSON definitions for blog-post, blog-author, and blog-settings |
+| `../references/schema-reference.md` | Troubleshooting validation errors, checking field types, or looking up JSON-LD type details |
+| `../references/workflow-reference.md` | Running CLI operations (init, dev, push, pull, validate), fixing errors, or understanding dev mode behavior |
+
+## Intent Detection
+
+When invoked, check the user's message to determine intent. Follow one of three paths.
+
+### Path 1: No specific instructions
+
+The user invoked `/supatent:content-blog` without additional text, or with a vague message like "help with my blog."
+
+Check the current state:
+
+1. If `.supatent/schema/blog-post.json` does not exist -- no blog is set up yet:
+   > It looks like you have not set up a blog yet. I will create the blog schemas and your first post. Let me start with a few questions.
+   Then run the Interview Flow.
+
+2. If blog schemas exist but `.supatent/content/blog-post/` is empty or missing -- schemas exist, no content:
+   > Your blog schemas are ready but you do not have any posts yet. Want to create your first post?
+   Then run the Interview Flow.
+
+3. If blog content already exists -- ask what the user wants:
+   > You have an active blog with [N] posts. What would you like to do?
+   > - Write a new post
+   > - Update an existing post
+   > - Translate posts to another locale
+   > - Review SEO and structured data
+   > - Something else
+
+### Path 2: Specific instructions
+
+The user gave a clear directive (e.g., "translate posts to French", "update SEO on my posts", "I added a new locale").
+
+Do NOT run the Interview Flow. Instead:
+
+1. Investigate current state: read existing schemas, content files, and locale patterns
+2. Act on the request directly, asking clarifying questions only as needed
+3. For destructive operations (editing existing files): show what will change and ask for confirmation before writing
+
+### Path 3: New post request
+
+The user wants a new post (e.g., "write a post about X", "create a blog post about AI tools").
+
+Run the Interview Flow, but pre-fill answers from the invocation message. Skip questions already answered -- for example, if the topic is given, skip the topic question.
+
+### Intent signals
+
+| Signal words | Intent |
+|-------------|--------|
+| "new post", "write", "create", or no text | New post creation |
+| "translate", "locale", "language" | Multi-locale management |
+| "SEO", "JSON-LD", "structured data" | JSON-LD review and fix |
+| "update", "edit", "change" | Content modification |
+| "check", "review", "quality" | Content quality review |
+
+## Context Discovery
+
+Before the interview, gather existing context that can pre-fill answers. This reduces questions the user must answer.
+
+### Project context files
+
+Scan the project root and common documentation directories for:
+
+- **Tone/style:** files matching `*tone*guide*`, `*style*guide*`
+- **SEO keywords:** files matching `*keyword*`, `*seo*`
+- **Audience:** files matching `*audience*`, `*persona*`
+
+If the user mentions a specific document, read it directly.
+
+### Locale configuration
+
+Discover what locales the project uses by scanning existing content files.
+
+Scan `.supatent/content/` for files matching `*.{locale}.json`. Extract unique locale codes to identify:
+
+- **Primary locale:** the locale with the most content files
+- **Secondary locales:** all other detected locale codes
+
+If no content files exist yet, assume `en` as the primary locale and ask the user to confirm.
+
+## Interview Flow
+
+The full interview runs ONLY for new blog post creation. It has five questions. Skip any question where context already provides the answer.
+
+**Question 1 -- Topic and angle** (free-form)
+"What topic do you want to write about? What is your angle or thesis?"
+Skip if: the user stated the topic in their invocation message.
+
+**Question 2 -- Target audience** (free-form with suggestions)
+"Who is this post for? Examples: developers, marketers, executives, general audience."
+Skip if: an audience or persona document was found in the project, or the user mentioned the audience.
+
+**Question 3 -- Key points** (free-form)
+"What are the 3-5 main points or takeaways you want to cover?"
+Skip if: the user provided a detailed outline in their invocation message.
+
+**Question 4 -- Tone and style** (multi-choice)
+"What tone works best?
+(a) Professional and authoritative
+(b) Conversational and friendly
+(c) Technical and detailed
+(d) Casual and approachable"
+Skip if: a tone or style guide file was found in the project.
+
+**Question 5 -- SEO keywords** (free-form)
+"What keywords should this post target? For example: 'content strategy', 'SEO best practices'."
+Skip if: an SEO keyword list was found in the project.
+
+Ask all unanswered questions in a single message. Group them naturally as a conversation, not a numbered form.
+
+After gathering answers, summarize the brief back to the user:
+> Here is what I will create: [topic summary, audience, tone, key points]. Ready to generate?
+
+Then proceed to schema generation (if needed) and content generation.
+
+## Schema Generation
+
+Read `./blog-sections.md` to get the schema definitions.
+
+### First-time setup (no blog schemas exist)
+
+1. Create `.supatent/schema/blog-post.json` with the core fields from the catalog (title, excerpt, cover-image, body, json-ld)
+2. Ask the user about optional fields:
+   > The blog-post schema has three optional fields. Want me to add any of these?
+   > - **date-published** -- publication date (YYYY-MM-DD format)
+   > - **author** -- links to a blog-author entry by slug
+   > - **category** -- post category for filtering
+   Add the fields the user selects, adjusting `order` values accordingly.
+3. Create `.supatent/schema/blog-author.json`
+4. Create `.supatent/schema/blog-settings.json`
+5. Ask the user for their blog title, then create `.supatent/content/blog-settings/default.{primaryLocale}.json` with:
+   - `blog-title`: the user's answer
+   - `blog-description`: ask or generate a sensible default
+   - `posts-per-page`: default to 10
+
+If schemas already exist, skip this section entirely.
+
+After writing schema files, check `.supatent/.validation-status.json` to confirm validation passes. If errors appear, read `../references/workflow-reference.md` for fix instructions.
+
+## Content Generation
+
+Generate content based on interview answers. This is the core creative work.
+
+### Blog post
+
+Write to `.supatent/content/blog-post/{post-slug}.{locale}.json`.
+
+Generate a URL-friendly slug from the title (lowercase, hyphens, no special characters).
+
+**Body content:**
+- Default length: 1000-1500 words
+- Format: markdown with headings (H2, H3), paragraphs, lists, and emphasis as the content demands
+- SEO-conscious writing: include target keywords in the first paragraph, use semantic keyword variations throughout, structure headings around searchable concepts
+- Content-driven structure: do NOT use a rigid template. Let the topic dictate whether the post needs numbered lists, narrative flow, comparison tables, or a mix.
+- Match the tone and style the user selected in the interview
+
+**Field values:**
+
+| Field | Value |
+|-------|-------|
+| `title` | Clear, engaging title incorporating the primary keyword |
+| `excerpt` | 1-2 sentence summary, 150-160 characters ideal for meta description |
+| `cover-image` | Empty string `""` -- note to user: "Add a cover image asset slug after uploading via the dashboard or CLI" |
+| `body` | The full markdown article |
+| `date-published` | Today's date in YYYY-MM-DD format (if field exists on schema) |
+| `author` | Empty string `""` unless a blog-author content item exists (if field exists) |
+| `category` | Derived from topic (if field exists on schema) |
+| `json-ld` | Article structured data -- see JSON-LD section below |
+
+### Blog author (first-time setup only)
+
+If this is the first blog setup:
+1. Ask the user for their name
+2. Write to `.supatent/content/blog-author/{name-slug}.{locale}.json` with the `name` field
+3. Set the `author` field on the blog post to this author's slug
+
+### Content writing skill delegation
+
+If the user has a content writing skill installed (check `.claude/skills/` for writing-related skills), defer to that skill for the actual body content and handle only the Supatent-specific parts: schema creation, file structure, JSON-LD generation, and validation.
+
+## JSON-LD Article Generation
+
+Generate the `json-ld` field value for each blog post. Follow these rules strictly.
+
+### Required rules
+
+1. Use `@type: "Article"` -- NEVER `BlogPosting`. BlogPosting fails Supatent validation.
+2. Always include `@context: "https://schema.org"`.
+3. Include these properties when data is available:
+   - `headline`: same as the post title (max 110 characters)
+   - `author`: `{ "@type": "Person", "name": "Author Name" }` -- `name` is REQUIRED on the Person object
+   - `datePublished`: same as date-published field value (YYYY-MM-DD)
+   - `description`: same as excerpt
+   - `wordCount`: calculated from the body content
+   - `articleSection`: same as category if available
+4. Do NOT include `image` unless the user provides an actual URL. Asset slugs fail URI validation.
+5. Do NOT include `dateModified` on initial creation.
+6. Do NOT include properties not in the Article schema. The validator uses `additionalProperties: false`.
+
+### Example
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "Post Title Here",
+  "author": {
+    "@type": "Person",
+    "name": "Author Name"
+  },
+  "datePublished": "2026-02-13",
+  "description": "Brief description of the post.",
+  "wordCount": 1250,
+  "articleSection": "Category"
+}
+```
+
+### Troubleshooting
+
+After writing, check `.supatent/.validation-status.json` for errors. Common JSON-LD issues:
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `unsupported @type` | Using BlogPosting instead of Article | Change `@type` to `"Article"` |
+| `image: expected uri format` | Using asset slug instead of URL | Remove `image` or use a full URL |
+| `required property 'name' is missing` | Author object missing name | Add `"name"` to the author Person object |
+
+## Multi-Locale Translation
+
+After generating the primary locale content, handle translations for other configured locales.
+
+1. Check for other configured locales (from the locale discovery in Context Discovery)
+2. If other locales exist, inform the user:
+   > I see you have content in [locale list]. I will translate the post to these locales.
+3. Generate translated content files: `.supatent/content/blog-post/{slug}.{locale}.json`
+
+### Translation rules
+
+- Culturally adapted, not literal translation. Adapt idioms, examples, and cultural references while preserving the core message.
+- Keep the same slug across all locales.
+- Translate all text fields: title, excerpt, body.
+- JSON-LD: translate headline and description. Keep author name and datePublished unchanged.
+- Do NOT translate field keys -- they are schema slugs, not content.
+
+Translation proceeds automatically without confirmation (additive operation).
+
+If blog-settings or blog-author content exists in the primary locale but not in secondary locales, translate those too.
+
+If only one locale is configured, skip this section entirely.
+
+## Confirmation and Safety
+
+### Confirmation rules
+
+- **Additive operations** (creating new files: new schemas, new content items, new locale files): proceed without asking for confirmation.
+- **Destructive/modifying operations** (editing existing content files, changing schema fields): show a diff-style summary of what will change and ask "Proceed with these changes?" before writing.
+
+### Post-write validation
+
+Always validate after making changes. After all writes:
+- If dev mode is running (check with `pgrep -f "supatent dev"`), wait a moment for auto-validation
+- If dev mode is not running, suggest: `npx @supatent/cli validate`
+- Read `.supatent/.validation-status.json` and report any errors
+- If errors are found, fix them and re-validate
+
+## Image Guidance
+
+After content generation, provide image guidance to the user.
+
+**Required images:**
+- **Cover image** for the blog post: recommended size 1200x630px (OG image compatible). Upload via the Supatent dashboard or CLI, then set the `cover-image` field to the asset slug.
+
+**Nice-to-have images:**
+- **Author avatar:** 400x400px square, if the blog-author schema gains an avatar field later.
+- **In-body images:** if the post content references diagrams or screenshots, note which images would strengthen the post.
+
+Format the guidance as:
+> Here are the images you will need for this post: [list with recommended sizes and format notes]
+
+Remind the user that images can be uploaded via the Supatent dashboard (drag-and-drop) or via the CLI asset upload flow. After uploading, set the `cover-image` field value to the asset slug returned by the upload.