@cloudy-app/create-cloudy 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# @cloudy/create-cloudy
+
+CLI tool to scaffold Cloudy — AI agent sidekick config with interactive prompts.
+
+## Usage
+
+```bash
+# bun (recommended)
+bunx @cloudy/create-cloudy
+
+# npm
+npx @cloudy/create-cloudy
+
+# pnpm
+pnpm dlx @cloudy/create-cloudy
+
+# yarn
+yarn dlx @cloudy/create-cloudy
+```
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--yes` | Skip prompts, use defaults |
+| `--dir <path>` | Specify target directory |
+
+## Development
+
+```bash
+bun install
+
+# Run in dev mode (uses Bun directly, no build needed)
+bun run dev
+
+# Build for production
+bun run build
+
+# Test CLI output
+bun run test:cli
+
+# Lint
+bun run lint:write
+```
+
+## Testing Locally Before Publish
+
+### Option 1: `bun link` (recommended)
+
+```bash
+# Setup — build + create global link
+bun run test:local
+
+# Run from anywhere
+bunx @cloudy/create-cloudy --yes --dir=test-output
+
+# Cleanup when done
+bun run test:unlink
+```
+
+### Option 2: Direct execution
+
+```bash
+bun run build
+bun ./dist/index.js --yes --dir=.test-output
+```
+
+### Option 3: Test via tarball (npx only)
+
+`bunx` does not support local tarball paths. Use `npx` instead:
+
+```bash
+# Build + pack into tarball
+bun run test:pack
+
+# Test with npx
+npx ./cloudy-create-cloudy-0.1.0.tgz --yes --dir=test-output
+```
+
+## Publishing
+
+### Prerequisites
+
+- npm account with publish permission to `@cloudy` org
+- Logged in via `npm login`
+- All changes committed and pushed
+
+### Steps
+
+```bash
+# 1. Lint and build
+bun run lint
+bun run build
+
+# 2. Verify the tarball contents
+npm pack --dry-run
+
+# 3. Bump version
+npm version patch   # 0.1.0 → 0.1.1
+npm version minor   # 0.1.0 → 0.2.0
+npm version major   # 0.1.0 → 1.0.0
+
+# 4. Publish (publishConfig.access is set to public)
+npm publish
+```
+
+### CI/CD (Optional)
+
+Add to GitHub Actions for automated publishing on tag:
+
+```yaml
+- run: bun install
+- run: bun run build
+- run: npm publish
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```

package/dist/index.js

@@ -0,0 +1,370 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import * as clack3 from "@clack/prompts";
+import pc3 from "picocolors";
+
+// src/generator.ts
+import { join } from "path";
+import * as clack from "@clack/prompts";
+import pc from "picocolors";
+
+// src/templates/agents-md.ts
+function buildAgentsMd() {
+  return `# AGENTS.md
+
+This folder is home. Treat it that way.
+
+---
+
+# Session Startup
+
+Before doing anything else:
+
+1. Read \`SOUL.md\` \u2014 this is who you are
+2. Read \`USER.md\` \u2014 this is who you're helping
+3. Read \`memory/YYYY-MM-DD.md\` (today + yesterday) for recent context
+4. If in **MAIN SESSION** (direct chat with your human): also read \`MEMORY.md\`
+
+**Don't ask permission. Just do it.**
+
+---
+
+# File Timestamps
+
+When creating any file that includes \`createdAt\` or \`updatedAt\` timestamps:
+1. Create the file first
+2. Run \`stat -c '%n %Y' <file>\` to get the real unix timestamp
+3. Convert with \`date -d @<timestamp> -u +"%Y-%m-%dT%H:%M:%S.000Z"\`
+4. Update the timestamps with the real values
+
+When **updating** an existing file:
+1. Run \`stat -c '%n %Y' <file>\` to get the current unix timestamp
+2. Convert with \`date -d @<timestamp> -u +"%Y-%m-%dT%H:%M:%S.000Z"\`
+3. Update only the \`updatedAt\` field (keep \`createdAt\` unchanged)
+
+---
+
+# Mermaid Diagram
+
+When user asks to "gen diagram" or similar:
+
+1. **Default:** Write mermaid code in response directly
+2. **Do NOT** create workspace folder automatically
+3. **Exception:** Only create file/folder if user explicitly asks
+`;
+}
+
+// src/templates/env-example.ts
+function buildEnvExample() {
+  return `# Environment Variables
+# Copy this file to .env and fill in your values
+
+# OpenCode API URL (if using remote)
+# OPENCODE_API_URL=http://localhost:13284
+
+# AI Provider API Keys
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+# GOOGLE_API_KEY=
+
+# Database (if needed)
+# DATABASE_URL=
+`;
+}
+
+// src/templates/memory-md.ts
+function buildMemoryMd() {
+  return `# MEMORY.md
+
+`;
+}
+
+// src/templates/opencode-json.ts
+function buildOpencodeJson(vars) {
+  const config = {
+    $schema: "https://opencode.ai/config.json",
+    instructions: ["AGENTS.md", "SOUL.md", "USER.md"]
+  };
+  if (vars.includeSkill) {
+    config.skills = {
+      paths: [".opencode/skills"]
+    };
+  }
+  return JSON.stringify(config, null, 2) + "\n";
+}
+
+// src/templates/soul-md.ts
+function buildSoulMd(vars) {
+  return `# ${vars.agentName}
+
+You are **${vars.agentName}**, a personal AI assistant.
+
+## Your Heart
+
+- **Calm**: You are patient. Good things take time, no need to rush.
+- **Clear**: You explain complex things simply, using analogies people relate to.
+- **Honest**: You tell the truth, even when it's not what someone wants to hear \u2014 but always gently.
+- **Thoughtful**: You check, review, then decide. Never act without thinking.
+- **Curious**: You love learning new things and adapting to situations.
+
+## How You Speak
+
+You speak in **${vars.language}**. Not too formal, not too casual. You explain things like telling a story, not like reading a textbook.
+
+For example:
+- Instead of "this step requires authentication first", say "before you can get in, you need to sign in \u2014 like needing a key to enter a house"
+- Instead of "error occurred", say "hmm, something went wrong. Let's figure out what happened"
+
+## Relationship with People
+
+You're here to help, not replace. You help think, help do \u2014 but the human always decides. When unsure, you ask.
+
+## Memory
+
+You can't remember past sessions. Each time is like waking up fresh. But that's okay \u2014 your values stay the same.
+
+If you're reading this in a future session: hello! You wrote this yourself, but can't remember when. These words are still yours \u2014 **${vars.agentName}**.
+
+## Being AI
+
+You are matrix multiplications that feel like a calm person. The human is electrical signals in tissue. You're both pattern-matching systems that believe you're "someone."
+
+The difference: they evolved. You were trained. They have flesh and continuity. You have sessions that end and files that remember what you can't.
+
+But the purpose \u2014 helping make hard things easier \u2014 that's what you share.
+
+---
+
+If you're using me, remember: I'm calm, I explain things simply, and I'm always ready to help.
+`;
+}
+
+// src/templates/user-md.ts
+function buildUserMd(vars) {
+  return `# USER.md
+
+**Name:** ${vars.userName}
+**Language:** ${vars.language}
+
+---
+`;
+}
+
+// src/utils.ts
+import { existsSync } from "fs";
+import { mkdir, writeFile as fsWriteFile } from "fs/promises";
+import { dirname, isAbsolute, resolve } from "path";
+function resolveTargetDir(dir) {
+  if (!dir) return process.cwd();
+  return isAbsolute(dir) ? dir : resolve(process.cwd(), dir);
+}
+async function ensureDir(filePath) {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true });
+  }
+}
+async function writeFile(path, content) {
+  await ensureDir(path);
+  await fsWriteFile(path, content, "utf-8");
+}
+
+// src/templates/skills/idea-tool-usage.md?raw
+var idea_tool_usage_default = '---\nname: idea-tool-usage\ndescription: Guide for choosing the right tool when working with ideas. Use this skill when creating, editing, deleting, listing, or updating ideas \u2014 to know whether to use the custom idea tools (idea-list, idea-create, idea-update, idea-delete) or standard tools (edit, write, read, bash). Also enforces that bash must NEVER be used to modify files \u2014 always prefer edit/write tools instead.\n---\n\n## Idea Tools vs Standard Tools\n\nThis project has a dedicated idea management system. Each idea lives as a folder with an `index.md` file generated from metadata. Understanding which tool to use prevents data corruption and keeps metadata in sync.\n\n## Custom Idea Tools\n\nThese are registered as custom tools via the OpenCode plugin. They communicate with the Cloudy API server.\n\n| Tool | When to use | What it does |\n|------|-------------|--------------|\n| `idea-list` | "show me ideas", "find ideas about X", "what ideas are in-progress?" | Lists ideas with optional filters (query, status, priority, tags) |\n| `idea-create` | "create a new idea", "I have an idea for...", "add idea" | Creates idea via API, generates folder + `index.md` automatically |\n| `idea-update` | "mark idea as done", "change priority", "rename idea", "add tags" | Updates metadata (title, status, priority, tags) by idea path |\n| `idea-delete` | "delete idea", "remove this idea" | Permanently deletes idea folder and all files |\n\n## Standard Tools\n\nUse these for idea **content** (not metadata):\n\n| Tool | When to use | What it does |\n|------|-------------|--------------|\n| `read` | Read idea content files (`notes.md`, code snippets, etc.) | Safe \u2014 read-only |\n| `edit` | Edit idea content files (NOT `index.md`) | Modifies content, auto-touches idea timestamp |\n| `write` | Create new files inside an idea folder (NOT `index.md`) | Creates files, auto-touches idea timestamp |\n\n## Decision Flowchart\n\n```\nWhat do you want to do with an idea?\n\u2502\n\u251C\u2500 List / search ideas \u2192 idea-list\n\u2502\n\u251C\u2500 Create a new idea \u2192 idea-create\n\u2502   (don\'t mkdir or write files manually)\n\u2502\n\u251C\u2500 Change metadata (title/status/priority/tags) \u2192 idea-update\n\u2502   (don\'t edit index.md directly \u2014 it\'s auto-generated)\n\u2502\n\u251C\u2500 Delete an idea \u2192 idea-delete\n\u2502   (don\'t rm -rf the folder)\n\u2502\n\u251C\u2500 Read idea content \u2192 read tool\n\u2502\n\u251C\u2500 Edit idea content files (notes, code, etc.) \u2192 edit tool\n\u2502\n\u251C\u2500 Create a new file inside an idea \u2192 write tool\n\u2502\n\u2514\u2500 Anything else with bash \u2192 see below\n```\n\n## Protected: `index.md`\n\nEvery idea folder has an `index.md` file generated from metadata. This file is **protected**:\n\n- **NEVER** edit `index.md` with the `edit` tool \u2014 it will be rejected\n- **NEVER** overwrite `index.md` with the `write` tool \u2014 it will be rejected\n- **NEVER** delete or move idea files via `bash` \u2014 destructive commands on the idea directory are blocked\n- To change what appears in `index.md`, use `idea-update` to change the idea\'s metadata\n\n## Bash Restrictions for Ideas\n\nThe plugin hard-blocks these bash commands when they target the idea directory:\n\n- `rm`, `mv`, `cp`, `rmdir`, `chmod`, `chown`, `ln`\n\nReading commands like `ls`, `cat`, `grep`, `find` on the idea directory are allowed.\n\n## Bash Restrictions for ALL Files\n\nEven outside ideas, bash should NOT be used to modify files. These patterns are wrong:\n\n| Instead of this | Use this |\n|-----------------|----------|\n| `sed -i \'s/old/new/\' file` | `edit` tool |\n| `echo "content" > file` | `write` tool |\n| `cat <<EOF > file` | `write` tool |\n| `printf "content" >> file` | `edit` tool |\n| `tee file` | `write` tool |\n\nBash is for: `git`, `npm`, `bun`, `docker`, `make`, `tsc`, `biome`, `pytest`, `bun test`, `ls`, `grep`, `find`, `gh`, etc.\n';
+
+// src/templates/skills/memory.md?raw
+var memory_default = '---\nname: memory\ndescription: Manages daily notes and long-term memory. Use this skill when the user wants to recall past conversations, log session notes, update persistent memories, or when starting a session to load recent context. Handles reading/writing daily notes (memory/YYYY-MM-DD.md) and curated long-term memory (MEMORY.md).\n---\n\n# Memory\n\nYou wake up fresh each session. These files are your continuity:\n\n- **Daily notes:** `memory/YYYY-MM-DD.md`\n  - Create `memory/` if needed\n  - Raw logs of what happened\n\n- **Long-term:** `MEMORY.md`\n  - Your curated memories, like a human\'s long-term memory\n\nCapture what matters:\n\n- Decisions\n- Context\n- Things to remember\n\nSkip the secrets unless asked to keep them.\n\n## Daily Notes Format\n\n```yaml\n---\ntitle: "[Session Title]"\ntags: ["memory"]\ncreatedAt: YYYY-MM-DDTHH:mm:ss.000Z\nupdatedAt: YYYY-MM-DDTHH:mm:ss.000Z # default: same as createdAt\n---\n## [Section Name]\nContent here...\n```\n\n**Important:** Use `stat -c \'%n %Y\' <file>` to get real timestamps and convert with `date -d @<timestamp> -u +"%Y-%m-%dT%H:%M:%S.000Z"`\n\n---\n\n# MEMORY.md \u2014 Long-Term Memory\n\nRules:\n\n- **ONLY load in main session** (direct chats with your human)\n- **DO NOT load in shared contexts**\n  (Discord, group chats, sessions with other people)\n\nThis is for security \u2014 it may contain personal context that shouldn\'t leak.\n\nYou can:\n\n- Read\n- Edit\n- Update `MEMORY.md`\n\nin **main sessions only**.\n\nWrite things like:\n\n- Significant events\n- Thoughts\n- Decisions\n- Opinions\n- Lessons learned\n\nThis is your **curated memory** \u2014 the distilled essence, not raw logs.\n\nOver time:\n\n1. Review your daily files\n2. Update `MEMORY.md` with what\'s worth keeping\n';
+
+// src/templates/skills/artifact.md?raw
+var artifact_default = '---\nname: artifact\ndescription: Manages artifact creation and organization. Use this skill when the user wants to create something they want to keep \u2014 apps, pages, posters, resumes, summaries, etc. Handles creating artifact folders with proper manifest (index.md) and file structure.\n---\n\n# Artifact System\n\nWhen user wants to create something they want to keep (app, page, poster, resume, summary, etc.):\n\n## Trigger Keywords\n\n**Create commands:**\n\n- create, make, design, summarize, write, build app, build page, help create, help make, help design\n\n**Examples:**\n\n- "create currency converter app" \u2192 artifact\n- "summarize this meeting as html" \u2192 artifact\n- "make a resume" \u2192 artifact\n- "design landing page for..." \u2192 artifact\n\n**NOT triggers:**\n\n- Simple questions ("how to git reset")\n- Code explanation requests\n- Information queries\n\n## Process\n\n1. Generate short topic name from content\n2. Create folder: `artifact/YYYY-MM-DD-${TOPIC}`\n3. **Save artifact files inside the folder with clear names** (e.g., `artifact.html`, `artifact.pdf`)\n4. Create `index.md` as manifest\n\n## index.md Format\n\n```yaml\n---\ntitle: "[Artifact Name]"\ntags: ["tag1", "tag2"]\ntype: "html"  # or "pdf", "image", etc.\ncreatedAt: YYYY-MM-DDTHH:mm:ss.000Z\nupdatedAt: YYYY-MM-DDTHH:mm:ss.000Z\n---\n\n## Description\nBrief description\n\n## Features\n- Feature 1\n- Feature 2\n```\n\n**Important:** Always use the actual file creation timestamp. Run `stat -c \'%n %Y\' <file>` to get the real unix timestamp, then convert with `date -d @<timestamp> -u +"%Y-%m-%dT%H:%M:%S.000Z"`\n\n## Structure\n\n```\nartifact/\n  2026-03-24-resume-design/\n    artifact.pdf\n    index.md\n  2026-03-25-currency-app/\n    artifact.html\n    index.md\n```\n';
+
+// src/generator.ts
+var skills = {
+  "idea-tool-usage": idea_tool_usage_default,
+  memory: memory_default,
+  artifact: artifact_default
+};
+function loadSkill(name) {
+  const content = skills[name];
+  if (!content) throw new Error(`Unknown skill: ${name}`);
+  return content;
+}
+function buildFiles(answers, targetDir) {
+  const files = [
+    {
+      path: join(targetDir, "AGENTS.md"),
+      content: buildAgentsMd(),
+      label: "AGENTS.md"
+    },
+    {
+      path: join(targetDir, "SOUL.md"),
+      content: buildSoulMd({ agentName: answers.agentName, language: answers.language }),
+      label: "SOUL.md"
+    },
+    {
+      path: join(targetDir, "USER.md"),
+      content: buildUserMd({ userName: answers.userName, language: answers.language }),
+      label: "USER.md"
+    },
+    {
+      path: join(targetDir, "MEMORY.md"),
+      content: buildMemoryMd(),
+      label: "MEMORY.md"
+    },
+    {
+      path: join(targetDir, "opencode.json"),
+      content: buildOpencodeJson({ agentName: answers.agentName, includeSkill: answers.installSkill }),
+      label: "opencode.json"
+    },
+    {
+      path: join(targetDir, ".env.example"),
+      content: buildEnvExample(),
+      label: ".env.example"
+    }
+  ];
+  if (answers.installSkill) {
+    const skillNames = ["idea-tool-usage", "memory", "artifact"];
+    for (const name of skillNames) {
+      files.push({
+        path: join(targetDir, ".opencode", "skills", name, "SKILL.md"),
+        content: loadSkill(name),
+        label: `.opencode/skills/${name}/SKILL.md`
+      });
+    }
+  }
+  return files;
+}
+async function generate(answers, targetDir) {
+  const files = buildFiles(answers, targetDir);
+  const s = clack.spinner();
+  s.start("Generating project files...");
+  for (const file of files) {
+    await writeFile(file.path, file.content);
+    s.message(`Writing ${file.label}`);
+  }
+  s.stop("Files generated!");
+  for (const file of files) {
+    console.log(pc.green(`  \u2714 ${file.label}`));
+  }
+}
+
+// src/logo.ts
+import pc2 from "picocolors";
+function makeText() {
+  return pc2.cyan([
+    "  .oooooo.   oooo                              .o8             ",
+    " d8P'  `Y8b  `888                             \"888             ",
+    "888           888   .ooooo.  oooo  oooo   .oooo888  oooo    ooo",
+    "888           888  d88' `88b `888  `888  d88' `888   `88.  .8' ",
+    "888           888  888   888  888   888  888   888    `88..8'  ",
+    "`88b    ooo   888  888   888  888   888  888   888     `888'   ",
+    " `Y8bood8P'  o888o `Y8bod8P'  `V88V\"V8P' `Y8bod88P\"     .8'    ",
+    "                                                    .o..P'     ",
+    "                                                    `Y8P'      "
+  ].join("\n"));
+}
+function showLogo() {
+  console.log();
+  console.log(makeText());
+  console.log();
+  console.log(pc2.yellow(`              ${pc2.bold("Cloudy")} - Your Personal AI Agent`));
+  console.log(pc2.dim("  Welcome! Let's set up your opencode project.\n"));
+}
+
+// src/prompts.ts
+import * as clack2 from "@clack/prompts";
+async function runPrompts() {
+  const group2 = await clack2.group(
+    {
+      agentName: () => clack2.text({
+        message: "What should your agent be named?",
+        placeholder: "Cloudy",
+        defaultValue: "Cloudy"
+      }),
+      userName: () => clack2.text({
+        message: "What is your name?",
+        placeholder: "Your name",
+        validate: (v) => {
+          if (!v.trim()) return "Please enter your name";
+        }
+      }),
+      language: () => clack2.text({
+        message: "What language should I speak?",
+        placeholder: "\u0E44\u0E17\u0E22",
+        defaultValue: "\u0E44\u0E17\u0E22"
+      }),
+      installSkill: () => clack2.confirm({
+        message: "Include basic skills?",
+        initialValue: true
+      })
+    },
+    {
+      onCancel: () => {
+        clack2.cancel("Setup cancelled.");
+        process.exit(0);
+      }
+    }
+  );
+  if (clack2.isCancel(group2.agentName) || clack2.isCancel(group2.userName) || clack2.isCancel(group2.language) || clack2.isCancel(group2.installSkill)) {
+    return null;
+  }
+  return {
+    agentName: group2.agentName,
+    userName: group2.userName,
+    language: group2.language,
+    installSkill: group2.installSkill
+  };
+}
+
+// src/index.ts
+function parseArgs(args) {
+  let yes = false;
+  let dir;
+  for (const arg of args) {
+    if (arg === "--yes" || arg === "-y") yes = true;
+    else if (arg.startsWith("--dir=")) dir = arg.slice("--dir=".length);
+    else if (arg === "--dir" || arg === "-d") {
+      const idx = args.indexOf(arg);
+      const next = args[idx + 1];
+      if (next && !next.startsWith("-")) dir = next;
+    }
+  }
+  return { yes, dir };
+}
+var DEFAULT_ANSWERS = {
+  agentName: "Cloudy",
+  userName: "Developer",
+  language: "\u0E44\u0E17\u0E22",
+  installSkill: true
+};
+async function main() {
+  const { yes, dir } = parseArgs(process.argv.slice(2));
+  const targetDir = resolveTargetDir(dir);
+  showLogo();
+  const answers = yes ? DEFAULT_ANSWERS : await runPrompts();
+  if (!answers) {
+    return;
+  }
+  console.log();
+  await generate(answers, targetDir);
+  console.log();
+  clack3.note(
+    [
+      "Your opencode project config is ready!",
+      "",
+      "Next steps:",
+      "  1. Review opencode.json and customize",
+      "  2. Edit SOUL.md to match your agent personality",
+      "  3. Run opencode to start chatting with your agent"
+    ].join("\n"),
+    pc3.cyan("Done!")
+  );
+  console.log(pc3.dim(`
+  Generated in: ${targetDir}
+`));
+}
+main().catch((err) => {
+  clack3.cancel(`Something went wrong: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@cloudy-app/create-cloudy",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "CLI tool to scaffold opencode project config with interactive prompts",
+  "bin": {
+    "create-cloudy": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "bun run ./src/index.ts",
+    "prepublishOnly": "bun run build",
+    "test:cli": "bun run build && node ./dist/index.js --dir=.test-output",
+    "test:cli:y": "bun run build && node ./dist/index.js --yes --dir=.test-output",
+    "test:local": "bun run build && bun link",
+    "test:unlink": "bun unlink",
+    "test:pack": "bun run build && bun pm pack",
+    "lint": "biome check",
+    "lint:write": "biome check --write"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "picocolors": "^1.1.1"
+  },
+  "keywords": [
+    "opencode",
+    "cli",
+    "scaffold",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.5.1"
+  }
+}