skillflow-ai 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# skillflow-ai
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Install [SkillFlow AI](https://directory.skillflow.ai.id) skills into Claude Code, Codex, or any agent's skills folder with
+one command, and keep them up to date.
+
+Needs a SkillFlow **Pro** account and Node.js 18 or newer.
+
+## Start
+
+1. Open the SkillFlow directory, go to **CLI token**, and make a token (it is shown once).
+2. On your computer:
+
+```bash
+npx skillflow-ai login
+```
+
+Paste the token. It is saved in `~/.skillflow/config.json`, readable only by you.
+
+## Commands
+
+```bash
+npx skillflow-ai list                         # skills you can install
+npx skillflow-ai add carousel-ringkasan-buku  # into ~/.claude/skills
+npx skillflow-ai add <slug> --agent codex     # into ~/.codex/skills
+npx skillflow-ai add <slug> --project         # into ./.claude/skills of this folder
+npx skillflow-ai add <slug> --dir <folder>    # any folder (Antigravity and others)
+npx skillflow-ai update                       # update everything you installed
+npx skillflow-ai themes                       # colour themes for the result
+npx skillflow-ai add <slug> --theme hijau-daun  # result in that theme (THEME.md in the skill)
+npx skillflow-ai add <slug> --colors "#1F5E3B,#F2B33D"  # or your own two colours
+npx skillflow-ai remove <slug>
+npx skillflow-ai whoami
+npx skillflow-ai logout
+```
+
+If you have a brand profile on the directory, every skill you add carries it as `BRAND.md`.
+
+The token stops working when your account leaves Pro, or when you revoke it on the directory.

package/bin/skillflow.mjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+// SkillFlow CLI: install SkillFlow skills into Claude Code, Codex or any folder with one command.
+// Needs a personal token from the SkillFlow directory (Pro). No dependencies; Node 18+.
+import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, renameSync, chmodSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve, dirname } from 'node:path'
+import { createInterface } from 'node:readline'
+import { readZip } from '../lib/unzip.mjs'
+
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+const HOME = process.env.SKILLFLOW_HOME || join(homedir(), '.skillflow')
+const CONFIG = join(HOME, 'config.json')
+const INSTALLED = join(HOME, 'installed.json')
+const DEFAULT_SERVER = 'https://directory.skillflow.ai.id'
+const AGENTS = { claude: join(homedir(), '.claude', 'skills'), codex: join(homedir(), '.codex', 'skills') }
+const PROJECT = { claude: join('.claude', 'skills'), codex: join('.codex', 'skills') }
+
+const say = (...a) => console.log(...a)
+const fail = (msg, code = 1) => { console.error('✗ ' + msg); process.exit(code) }
+
+function readJson(file, fallback) {
+  try { return JSON.parse(readFileSync(file, 'utf8')) } catch { return fallback }
+}
+function writePrivate(file, data) {
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 })
+  writeFileSync(file, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 })
+  try { chmodSync(file, 0o600) } catch {}
+}
+const config = () => readJson(CONFIG, {})
+const server = () => (process.env.SKILLFLOW_SERVER || config().server || DEFAULT_SERVER).replace(/\/+$/, '')
+
+function parse(argv) {
+  const args = []; const opts = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) {
+      const [k, v] = a.slice(2).split('=')
+      if (v !== undefined) opts[k] = v
+      else if (argv[i + 1] && !argv[i + 1].startsWith('-') && ['agent', 'dir', 'server', 'kind', 'token', 'theme', 'colors'].includes(k)) opts[k] = argv[++i]
+      else opts[k] = true
+    } else if (a === '-h') opts.help = true
+    else args.push(a)
+  }
+  return { args, opts }
+}
+
+async function api(path, { raw = false, token = config().token } = {}) {
+  if (!token) fail('Not logged in. Make a token on the SkillFlow directory (Pro), then run: npx skillflow-ai login')
+  let res
+  try {
+    res = await fetch(server() + path, { headers: { Authorization: 'Bearer ' + token, Accept: raw ? 'application/zip' : 'application/json', 'User-Agent': 'skillflow-cli/' + VERSION } })
+  } catch (e) { fail('Could not reach ' + server() + ' (' + e.message + ').') }
+  if (!res.ok) {
+    let body = {}
+    try { body = await res.json() } catch {}
+    fail(body.message || `The server answered ${res.status}.`, res.status === 401 || res.status === 403 ? 2 : 1)
+  }
+  return raw ? { buf: Buffer.from(await res.arrayBuffer()), version: res.headers.get('x-skillflow-version') } : res.json()
+}
+
+function ask(question) {
+  return new Promise(done => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    rl.question(question, a => { rl.close(); done(a.trim()) })
+  })
+}
+
+function targetDir(opts) {
+  if (opts.dir && opts.dir !== true) return resolve(opts.dir)
+  const agent = (opts.agent && opts.agent !== true ? opts.agent : 'claude').toLowerCase()
+  if (opts.project) {
+    if (!PROJECT[agent]) fail(`For --agent ${agent} use --dir <folder>.`)
+    return resolve(PROJECT[agent])
+  }
+  if (!AGENTS[agent]) fail(`No default folder for --agent ${agent}. Use --dir <folder> (the agent's skills folder).`)
+  return AGENTS[agent]
+}
+
+// Colour theme of the result, sent as the same `?tema=` the directory's ZIP link uses. undefined = not given,
+// '' = no theme (the skill's own colours; also how --theme default clears a saved one).
+function themeQuery(opts) {
+  if (opts.colors && opts.colors !== true) {
+    const c = String(opts.colors).split(',').map(s => s.trim())
+    if (c.length !== 2 || !c.every(x => /^#?[0-9a-fA-F]{6}$/.test(x))) fail('--colors takes two hex colours: --colors "#1F5E3B,#F2B33D"')
+    const hex = c.map(x => (x.startsWith('#') ? x : '#' + x).toUpperCase())
+    return `?tema=custom&utama=${encodeURIComponent(hex[0])}&aksen=${encodeURIComponent(hex[1])}`
+  }
+  if (opts.theme === undefined) return undefined
+  if (opts.theme === true) fail('Name a theme: --theme <name> (see: npx skillflow-ai themes)')
+  if (['default', 'none'].includes(opts.theme)) return ''
+  if (!/^[a-z-]{1,40}$/.test(opts.theme)) fail(`"${opts.theme}" is not a theme name. See: npx skillflow-ai themes`)
+  return `?tema=${opts.theme}`
+}
+
+async function install(slug, dir, theme = '') {
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(slug)) fail(`"${slug}" is not a skill name.`)
+  const { buf, version } = await api(`/api/skills/v1/skills/${slug}/bundle${theme}`, { raw: true })
+  const entries = readZip(buf)
+  // Bundles hold "<slug>/…". Anything outside that folder is ignored.
+  const own = entries.filter(e => e.name === slug + '/' || e.name.startsWith(slug + '/'))
+  if (!own.some(e => !e.dir)) fail(`The bundle for ${slug} is empty.`)
+  mkdirSync(dir, { recursive: true })
+  const final = join(dir, slug)
+  const tmp = join(dir, `.${slug}.skillflow-tmp-${process.pid}`)
+  rmSync(tmp, { recursive: true, force: true })
+  for (const e of own) {
+    const path = join(tmp, e.name.slice(slug.length + 1))
+    if (!resolve(path).startsWith(resolve(tmp))) fail(`unsafe path in bundle: ${e.name}`)
+    if (e.dir) { mkdirSync(path, { recursive: true }); continue }
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, e.data)
+  }
+  // Swap in one step, so a failed download never leaves a half-written skill.
+  rmSync(final, { recursive: true, force: true })
+  renameSync(tmp, final)
+  const list = readJson(INSTALLED, {})
+  list[final] = { slug, version: version || null, dir, theme: theme || null, at: new Date().toISOString() }
+  writePrivate(INSTALLED, list)
+  return { final, version }
+}
+
+const HELP = `skillflow ${VERSION}: install SkillFlow skills into your AI agent
+
+  npx skillflow-ai login [--token sf_…] [--server URL]   save your personal token (make it on the directory, Pro)
+  npx skillflow-ai whoami                                who the token belongs to
+  npx skillflow-ai list [--kind video]                   skills you can install
+  npx skillflow-ai add <slug> [<slug>…]                  install into ~/.claude/skills
+        --theme <name> | --colors "#hex,#hex"            colour theme of the result (THEME.md)
+        --agent codex                                    ~/.codex/skills instead
+        --project                                        ./.claude/skills (or ./.codex/skills) in this folder
+        --dir <folder>                                   any folder (Antigravity and other agents)
+  npx skillflow-ai update [<slug>]                       update installed skills to the latest version
+        --theme <name> | --colors … | --theme default    change the colour theme while updating
+  npx skillflow-ai themes                                list the colour themes
+  npx skillflow-ai remove <slug> [--dir <folder>]        delete an installed skill
+  npx skillflow-ai logout                                forget the token on this computer
+`
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2)
+  const { args, opts } = parse(rest)
+  switch (cmd) {
+    case 'login': {
+      const token = opts.token && opts.token !== true ? opts.token : await ask('Paste your SkillFlow token: ')
+      if (!/^sf_[A-Za-z0-9]{20,}$/.test(token)) fail('That does not look like a SkillFlow token (it starts with sf_).')
+      const base = opts.server && opts.server !== true ? opts.server.replace(/\/+$/, '') : undefined
+      if (base) process.env.SKILLFLOW_SERVER = base
+      const me = await api('/api/skills/v1/me', { token })
+      writePrivate(CONFIG, { ...config(), token, ...(base ? { server: base } : {}) })
+      say(`✓ Logged in as ${me.name} (${me.plan}). Token saved in ${CONFIG}.`)
+      if (me.brand_profile) say(`  Skills you add carry your brand profile "${me.brand_profile}" as BRAND.md.`)
+      break
+    }
+    case 'logout': {
+      const c = config(); delete c.token; writePrivate(CONFIG, c)
+      say('✓ Token removed from this computer. (Revoke it on the directory too if it may have leaked.)')
+      break
+    }
+    case 'whoami': {
+      const me = await api('/api/skills/v1/me')
+      say(`${me.name} · ${me.plan}${me.brand_profile ? ` · brand profile: ${me.brand_profile}` : ''} · ${server()}`)
+      break
+    }
+    case 'list': {
+      const { skills } = await api('/api/skills/v1/catalog')
+      const installed = new Set(Object.values(readJson(INSTALLED, {})).map(r => r.slug))
+      const rows = skills.filter(s => s.installable && (!opts.kind || s.kind === opts.kind))
+      for (const s of rows) say(`${installed.has(s.slug) ? '✓' : ' '} ${s.slug.padEnd(42)} ${s.kind.padEnd(12)} v${s.version}  ${s.title}`)
+      say(`\n${rows.length} skill(s). Install one with: npx skillflow-ai add <slug>`)
+      break
+    }
+    case 'add': {
+      if (!args.length) fail('Name a skill: npx skillflow-ai add <slug>')
+      const dir = targetDir(opts)
+      const theme = themeQuery(opts) ?? ''
+      for (const slug of args) {
+        const r = await install(slug, dir, theme)
+        say(`✓ ${slug}${r.version ? ' v' + r.version : ''} → ${r.final}`)
+      }
+      break
+    }
+    case 'update': {
+      const list = readJson(INSTALLED, {})
+      const want = Object.entries(list).filter(([, r]) => !args.length || args.includes(r.slug))
+      if (!want.length) { say('Nothing installed yet.'); break }
+      const { skills } = await api('/api/skills/v1/catalog')
+      const latest = Object.fromEntries(skills.map(s => [s.slug, s.version]))
+      // The theme a skill was installed with is kept; --theme / --colors replaces it (and reinstalls).
+      const given = themeQuery(opts)
+      let n = 0
+      for (const [, r] of want) {
+        if (!latest[r.slug]) { say(`- ${r.slug}: no longer in the catalog (left as it is)`); continue }
+        const theme = given ?? (r.theme || '')
+        if (latest[r.slug] === r.version && !opts.force && theme === (r.theme || '')) continue
+        const res = await install(r.slug, r.dir, theme)
+        say(`✓ ${r.slug} ${r.version || '?'} → ${res.version || latest[r.slug]}`); n++
+      }
+      say(n ? `${n} skill(s) updated.` : 'Everything is up to date.')
+      break
+    }
+    case 'themes': {
+      const { themes } = await api('/api/skills/v1/catalog')
+      if (!themes || !themes.length) { say('This directory has no colour themes yet.'); break }
+      for (const t of themes) say('  ' + t)
+      say('\nUse one with: npx skillflow-ai add <slug> --theme ' + themes[0])
+      say('Or your own two colours: --colors "#1F5E3B,#F2B33D". Without either, the skill keeps its own colours.')
+      break
+    }
+    case 'remove': {
+      if (!args.length) fail('Name a skill: npx skillflow-ai remove <slug>')
+      const list = readJson(INSTALLED, {})
+      for (const slug of args) {
+        const keys = Object.keys(list).filter(k => list[k].slug === slug && (!opts.dir || list[k].dir === resolve(opts.dir)))
+        if (!keys.length) { say(`- ${slug}: not installed by skillflow`); continue }
+        for (const k of keys) { rmSync(k, { recursive: true, force: true }); delete list[k]; say(`✓ removed ${k}`) }
+      }
+      writePrivate(INSTALLED, list)
+      break
+    }
+    case '--version': case '-v': case 'version': say(VERSION); break
+    default: say(HELP); if (cmd && cmd !== 'help' && cmd !== '--help') process.exit(1)
+  }
+}
+
+main().catch(e => fail(e.message))

package/lib/unzip.mjs

@@ -0,0 +1,52 @@
+// Minimal ZIP reader (stored + deflate), enough for SkillFlow skill bundles. No dependencies.
+// Every entry name is checked before it becomes a path: no absolute paths, no "..", no drive letters.
+import { inflateRawSync } from 'node:zlib'
+
+const EOCD = 0x06054b50
+const CEN = 0x02014b50
+const LOC = 0x04034b50
+
+/** @returns {{name: string, dir: boolean, data: Buffer}[]} */
+export function readZip(buf) {
+  let eocd = -1
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 65535); i--) {
+    if (buf.readUInt32LE(i) === EOCD) { eocd = i; break }
+  }
+  if (eocd < 0) throw new Error('not a ZIP file')
+  const count = buf.readUInt16LE(eocd + 10)
+  let p = buf.readUInt32LE(eocd + 16)
+  const out = []
+  for (let n = 0; n < count; n++) {
+    if (buf.readUInt32LE(p) !== CEN) throw new Error('broken ZIP directory')
+    const method = buf.readUInt16LE(p + 10)
+    const csize = buf.readUInt32LE(p + 20)
+    const nameLen = buf.readUInt16LE(p + 28)
+    const extraLen = buf.readUInt16LE(p + 30)
+    const commentLen = buf.readUInt16LE(p + 32)
+    const local = buf.readUInt32LE(p + 42)
+    const name = buf.subarray(p + 46, p + 46 + nameLen).toString('utf8')
+    p += 46 + nameLen + extraLen + commentLen
+
+    if (buf.readUInt32LE(local) !== LOC) throw new Error('broken ZIP entry')
+    const start = local + 30 + buf.readUInt16LE(local + 26) + buf.readUInt16LE(local + 28)
+    const raw = buf.subarray(start, start + csize)
+    const dir = name.endsWith('/')
+    let data = Buffer.alloc(0)
+    if (!dir) {
+      if (method === 0) data = Buffer.from(raw)
+      else if (method === 8) data = inflateRawSync(raw)
+      else throw new Error(`unsupported compression in ${name}`)
+    }
+    out.push({ name: safeName(name), dir, data })
+  }
+  return out
+}
+
+/** A relative POSIX path, or an error. */
+export function safeName(name) {
+  const n = name.replace(/\\/g, '/')
+  if (!n || n.startsWith('/') || /^[a-zA-Z]:/.test(n) || n.split('/').some(part => part === '..')) {
+    throw new Error(`unsafe path in ZIP: ${name}`)
+  }
+  return n
+}

package/package.json

@@ -1,6 +1,13 @@
 {
   "name": "skillflow-ai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Install SkillFlow AI skills into Claude Code, Codex or any agent folder with one command.",
+  "type": "module",
+  "bin": { "skillflow-ai": "bin/skillflow.mjs", "skillflow": "bin/skillflow.mjs" },
+  "files": ["bin", "lib", "README.md"],
+  "engines": { "node": ">=18" },
+  "keywords": ["skillflow", "claude-code", "codex", "ai-agent", "skills"],
+  "homepage": "https://directory.skillflow.ai.id",
+  "license": "UNLICENSED",
+  "scripts": { "test": "node test/unzip.test.mjs" }
+}