@dastyaresocial/ds-cs 0.0.0-stage → 0.1.0

package/src/commands/target.mjs

@@ -0,0 +1,83 @@
+import { toArray } from "../args.mjs";
+
+/**
+ * Split `owner/repo@skill` into source and skill names.
+ *
+ * The `@` is only a separator on the *right*, and only when what follows looks
+ * like skill names. That guard matters for SSH remotes: in
+ * `git@github.com:owner/repo` the `@` sits in the middle and the remainder is a
+ * path, not a name. Requiring `name[,name…]` shaped like identifiers keeps that
+ * URL intact.
+ *
+ * `explicit` distinguishes "the user wrote `source@names`" from "no `@` was
+ * present" — without it a bare skill name would be misread as a source.
+ */
+const SKILL_NAME_LIST = /^[A-Za-z0-9_.-]+(,[A-Za-z0-9_.-]+)*$/;
+
+export function parseTarget(spec) {
+  const at = spec.lastIndexOf("@");
+  if (at > 0) {
+    const source = spec.slice(0, at);
+    const raw = spec.slice(at + 1).trim();
+    if (source && raw && SKILL_NAME_LIST.test(raw)) {
+      return {
+        source,
+        names: raw.split(",").map((name) => name.trim()),
+        explicit: true,
+      };
+    }
+  }
+  return { source: spec, names: [], explicit: false };
+}
+
+function splitNames(value) {
+  return value.includes(",") ? value.split(",").map((name) => name.trim()) : [value];
+}
+
+/**
+ * Work out what to install from positional arguments plus the repeatable
+ * `--skill` flag.
+ *
+ * A bare name (`ds-cs add brand-config`) means "from the DS-CS registry" — the
+ * common case should not require the user to know where a skill lives. A bare
+ * `owner/repo` is GitHub shorthand and is treated as a source instead.
+ */
+export function resolveRequest(positional, flags) {
+  const skillFlags = toArray(flags.skill);
+
+  if (positional.length === 0) {
+    return { source: "", names: skillFlags };
+  }
+
+  const parsed = parseTarget(positional[0]);
+
+  if (parsed.explicit) {
+    // `owner/repo@skill` names both; any further positionals are more skill names.
+    return {
+      source: parsed.source,
+      names: [...parsed.names, ...positional.slice(1).flatMap(splitNames), ...skillFlags],
+    };
+  }
+
+  // Nothing carried an `@`, so every positional is a skill name. Resolve them
+  // against the DS-CS registry — unless the first one is clearly a source.
+  const first = positional[0];
+  if (looksLikeSource(first)) {
+    return { source: first, names: [...positional.slice(1).flatMap(splitNames), ...skillFlags] };
+  }
+
+  return { source: "", names: [...positional.flatMap(splitNames), ...skillFlags] };
+}
+
+function looksLikeSource(spec) {
+  return (
+    spec.startsWith(".") ||
+    spec.startsWith("/") ||
+    spec.startsWith("~") ||
+    spec.startsWith("http") ||
+    spec.startsWith("git@") ||
+    spec.startsWith("git://") ||
+    spec.startsWith("ssh://") ||
+    /^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(spec)
+  );
+}

package/src/commands/update.mjs

@@ -0,0 +1,94 @@
+import { CANONICAL_AGENT, skillsDirFor } from "../agents.mjs";
+import { readLockfile } from "../lockfile.mjs";
+import { refreshSkill } from "../install.mjs";
+import { toArray } from "../args.mjs";
+import { hashDirectory, exists } from "../utils/fs.mjs";
+import path from "node:path";
+import { log } from "../utils/log.mjs";
+import { select } from "../utils/prompt.mjs";
+
+/**
+ * Re-fetch locked skills and report what actually changed.
+ *
+ * The comparison is against the recorded `computedHash`, so a skill whose files
+ * were edited locally shows up as "modified" rather than being silently
+ * overwritten. The default is to leave those alone — an agent's local tweak is
+ * usually deliberate, and clobbering it on a routine `update` is the kind of
+ * surprise that makes people stop running the tool.
+ */
+export async function updateCommand(positional, flags, { projectRoot }) {
+  const lockfile = await readLockfile(projectRoot);
+  const all = Object.keys(lockfile.skills).sort();
+
+  if (all.length === 0) {
+    log.info("Nothing to update — no skills in skills-lock.json.");
+    return;
+  }
+
+  let names = [...positional, ...toArray(flags.skill)];
+
+  if (names.length === 0 || names.includes("*")) {
+    if (flags.yes) {
+      names = all;
+    } else {
+      const picked = await select("Which skills should be updated?", all.map((name) => ({
+        label: name,
+        value: name,
+      })));
+      names = picked.map((choice) => choice.value);
+      if (names.length === 0) return;
+    }
+  }
+
+  let changed = 0;
+  let unchanged = 0;
+  let skipped = 0;
+  const problems = [];
+
+  for (const name of names) {
+    const entry = lockfile.skills[name];
+    if (!entry) {
+      log.warn(`"${name}" is not in skills-lock.json`);
+      continue;
+    }
+
+    const localDir = path.join(
+      skillsDirFor(CANONICAL_AGENT, { projectRoot, global: Boolean(flags.global) }),
+      name
+    );
+    const locallyModified = (await exists(localDir)) && (await hashDirectory(localDir)) !== entry.computedHash;
+
+    let result;
+    try {
+      result = await refreshSkill(projectRoot, entry, { global: Boolean(flags.global) });
+    } catch (error) {
+      problems.push(`${name}: ${error.message}`);
+      continue;
+    }
+
+    if (result.status === "missing") {
+      problems.push(`${name}: no longer present in ${result.source.describe()}`);
+      continue;
+    }
+
+    if (locallyModified && !flags.force) {
+      skipped += 1;
+      log.warn(`${name} has local changes — skipped (use --force to overwrite)`);
+      continue;
+    }
+
+    if (result.hash === entry.computedHash) {
+      unchanged += 1;
+    } else {
+      changed += 1;
+      log.success(`${name} updated`);
+    }
+  }
+
+  log.plain("");
+  log.info(`${changed} updated, ${unchanged} already current, ${skipped} skipped`);
+
+  for (const problem of problems) {
+    log.warn(problem);
+  }
+}

package/src/index.mjs

@@ -0,0 +1,176 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { parseArgs } from "./args.mjs";
+import { addCommand } from "./commands/add.mjs";
+import { loginCommand, logoutCommand, whoamiCommand } from "./commands/auth.mjs";
+import { initCommand } from "./commands/init.mjs";
+import { listCommand } from "./commands/list.mjs";
+import { mcpCommand } from "./commands/mcp.mjs";
+import { removeCommand } from "./commands/remove.mjs";
+import { searchCommand } from "./commands/search.mjs";
+import { updateCommand } from "./commands/update.mjs";
+import { CliError } from "./utils/errors.mjs";
+import { bold, log } from "./utils/log.mjs";
+
+const COMMANDS = [
+  "init",
+  "add",
+  "list",
+  "update",
+  "remove",
+  "search",
+  "mcp",
+  "login",
+  "whoami",
+  "logout",
+];
+
+const VERSION = await readVersion();
+
+const USAGE = `${bold("ds-cs")} — skills and tooling for Dastyare Social — CS
+
+${bold("Usage")}
+  ds-cs <command> [options]
+
+${bold("Commands")}
+  init [dir]              Prepare a project for DS-CS skills
+  add <skill|source>      Install skills from DS-CS or any skills repo
+  list                    Show installed skills and their sources
+  update [skill…]         Re-fetch installed skills that changed
+  remove <skill…>         Uninstall skills
+  search [query]          Search installed skills
+  mcp [agent]             Print (or write) MCP server config for a channel
+  login                   Store a channel URL + API key
+  whoami                  Show the stored channel
+  logout                  Remove stored credentials
+
+${bold("Sources")}
+  ds-cs add brand-config               from the DS-CS registry (default)
+  ds-cs add owner/repo                 from a GitHub repo
+  ds-cs add owner/repo@skill           pick one skill from that repo
+  ds-cs add ./my-skills                from a local directory
+  ds-cs add https://…/SKILL.md         from a direct URL
+
+${bold("Options")}
+  -s, --skill <name>    Install/remove this skill (repeatable, '*' for all)
+  -a, --agent <name>    Target agent, or a directory path starting with . or /
+  -g, --global          Install into the user directory instead of the project
+      --copy            Copy files instead of symlinking between agents
+  -y, --yes             Non-interactive; accept defaults
+      --list            List what a source offers instead of installing
+      --url <url>       Channel URL (login, mcp, init)
+      --api-key <key>   Channel API key (login, mcp, init)
+  -h, --help            Show this help
+  -v, --version         Print the CLI version
+
+${bold("Examples")}
+  ds-cs init --mcp
+  ds-cs add post-with-media
+  ds-cs add emilkowalski/skill@animate -a opencode
+  ds-cs login --url https://cs.example.com --api-key $KEY
+  ds-cs mcp claude-code > claude-mcp.json
+
+${bold("Environment")}
+  DS_CS_URL, DS_CS_API_KEY      used instead of a stored login
+  DS_CS_CONFIG_DIR              where credentials are stored
+  GITHUB_TOKEN / GH_TOKEN       for private skill repos
+`;
+
+async function readVersion() {
+  try {
+    const file = new URL("../package.json", import.meta.url);
+    return JSON.parse(await fs.readFile(file, "utf8")).version;
+  } catch {
+    return "0.0.0";
+  }
+}
+
+/**
+ * Find the project root by walking up for a VCS or package marker.
+ *
+ * Skills and the lockfile are project-scoped, so a `ds-cs add` run from a nested
+ * directory must land in the same place as one run from the root — otherwise the
+ * lockfile and the installed skills drift apart.
+ */
+async function findProjectRoot(startDir) {
+  let directory = path.resolve(startDir);
+  for (let depth = 0; depth < 20; depth += 1) {
+    const markers = [".git", "skills-lock.json", "package.json"];
+    for (const marker of markers) {
+      try {
+        await fs.stat(path.join(directory, marker));
+        return directory;
+      } catch {
+        // keep walking
+      }
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  return path.resolve(startDir);
+}
+
+export async function main(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs(argv);
+  } catch (error) {
+    throw new CliError(error.message, { hint: "Run `ds-cs --help`." });
+  }
+
+  const { flags, positional } = parsed;
+
+  if (flags.version) {
+    log.plain(VERSION);
+    return;
+  }
+
+  const command = positional.shift();
+
+  if (!command || flags.help) {
+    log.plain(USAGE);
+    return;
+  }
+
+  if (command === "help") {
+    log.plain(USAGE);
+    return;
+  }
+
+  const projectRoot = await findProjectRoot(flags.cwd ?? process.cwd());
+  const context = { projectRoot, version: VERSION };
+
+  switch (command) {
+    case "init":
+      return initCommand(positional, flags, context);
+    case "add":
+      return addCommand(positional, flags, context);
+    case "list":
+    case "ls":
+      return listCommand(positional, flags, context);
+    case "update":
+    case "upgrade":
+      return updateCommand(positional, flags, context);
+    case "remove":
+    case "rm":
+    case "uninstall":
+      return removeCommand(positional, flags, context);
+    case "search":
+    case "find":
+      return searchCommand(positional, flags, context);
+    case "mcp":
+      return mcpCommand(positional, flags, context);
+    case "login":
+      return loginCommand(positional, flags, context);
+    case "whoami":
+      return whoamiCommand(positional, flags, context);
+    case "logout":
+      return logoutCommand(positional, flags, context);
+    default:
+      throw new CliError(`Unknown command "${command}"`, {
+        hint: `Did you mean one of: ${COMMANDS.join(", ")}?`,
+      });
+  }
+}

package/src/install.mjs

@@ -0,0 +1,174 @@
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+
+import { CANONICAL_AGENT, dedupeDirectories, linkSkill, skillsDirFor } from "./agents.mjs";
+import { recordSkill } from "./lockfile.mjs";
+import { resolveSource } from "./registry/sources.mjs";
+import { assertSkillExists, discoverSkills } from "./skills/discover.mjs";
+import { CliError } from "./utils/errors.mjs";
+import {
+  copyDirectory,
+  ensureDir,
+  hashDirectory,
+  removeDirectory,
+} from "./utils/fs.mjs";
+import { select } from "./utils/prompt.mjs";
+
+/**
+ * Install skills from a source into one or more agents.
+ *
+ * The canonical copy always lands in `.agents/skills/<name>`, and every other
+ * target is linked to it. That ordering matters: it keeps one authoritative
+ * directory per project, so `ds-cs update` replaces content once instead of
+ * drifting per-agent copies.
+ */
+export async function installSkills({
+  source: sourceSpec,
+  names = [],
+  projectRoot,
+  targets,
+  global = false,
+  copy = false,
+  yes = false,
+  preferLocal = true,
+}) {
+  const resolved = await resolveSource(sourceSpec, { cwd: projectRoot, preferLocal });
+
+  const available = (await discoverSkills(resolved.root)).filter(
+    (skill) => process.env.INSTALL_INTERNAL_SKILLS === "1" || !skill.internal
+  );
+
+  if (available.length === 0) {
+    throw new CliError(`No skills found in ${resolved.describe()}`, {
+      hint: "A skill is a directory containing a SKILL.md with name and description frontmatter.",
+    });
+  }
+
+  const chosen = await chooseSkills(available, names, resolved, { yes });
+  if (chosen.length === 0) return { installed: [], resolved };
+
+  const canonicalDir = skillsDirFor(CANONICAL_AGENT, { projectRoot, global });
+  await ensureDir(canonicalDir);
+
+  const destinations = dedupeDirectories(
+    (targets?.length ? targets : [canonicalDir]).map((directory) =>
+      global && !path.isAbsolute(directory)
+        ? skillsDirFor(directory, { projectRoot, global })
+        : directory
+    )
+  );
+
+  const installed = [];
+  for (const skill of chosen) {
+    const destination = path.join(canonicalDir, skill.name);
+
+    // Replace rather than merge: a reference file removed upstream must not
+    // survive in the installed copy. Skipped when the source *is* the target,
+    // which happens if someone points `--source` at an installed skills dir —
+    // the delete below would otherwise destroy the source mid-copy.
+    if (!isSameDirectory(skill.dir, destination)) {
+      await removeDirectory(destination);
+      await copyDirectory(skill.dir, destination);
+    }
+
+    const hash = await hashDirectory(destination);
+    const links = [];
+    for (const target of destinations) {
+      if (path.resolve(target) === path.resolve(canonicalDir)) continue;
+      links.push(await linkSkill(destination, target, { copy }));
+    }
+
+    await recordSkill(projectRoot, { ...skill, hash }, resolved);
+    installed.push({ skill, destination, links, hash });
+  }
+
+  return { installed, resolved };
+}
+
+/** True when a copy from `source` to `destination` would clobber its own input. */
+function isSameDirectory(source, destination) {
+  return path.resolve(source) === path.resolve(destination);
+}
+
+async function chooseSkills(available, names, resolved, { yes }) {
+  if (names.includes("*")) return available;
+
+  if (names.length > 0) {
+    return names.map((name) => assertSkillExists(available, name));
+  }
+
+  if (yes) return [available[0]];
+
+  const picked = await select(`Which skills from ${resolved.describe()}?`, available.map((skill) => ({
+    label: skill.name,
+    value: skill,
+    description: skill.description,
+  })));
+
+  return picked.map((choice) => choice.value);
+}
+
+/**
+ * Re-install a locked skill from its recorded source.
+ *
+ * The lockfile stores the skill's path *within* the source (`skills/foo/SKILL.md`)
+ * so the same source can be re-fetched even if the skill moved within its own
+ * repository layout.
+ */
+export async function refreshSkill(projectRoot, entry, options = {}) {
+  const resolved = await resolveSource(entry.source, { cwd: projectRoot });
+  const available = await discoverSkills(resolved.root);
+  const match =
+    available.find((skill) => skill.name === entry.name) ??
+    available.find((skill) => skill.skillPath === entry.skillPath);
+
+  if (!match) {
+    return { name: entry.name, status: "missing", source: resolved };
+  }
+
+  const canonicalDir = skillsDirFor(CANONICAL_AGENT, {
+    projectRoot,
+    global: options.global ?? false,
+  });
+  const destination = path.join(canonicalDir, match.name);
+
+  if (!isSameDirectory(match.dir, destination)) {
+    await removeDirectory(destination);
+    await copyDirectory(match.dir, destination);
+  }
+  const hash = await hashDirectory(destination);
+
+  await recordSkill(projectRoot, { name: match.name, skillPath: match.skillPath, hash }, resolved);
+
+  return { name: match.name, status: "changed", source: resolved, hash, skill: match };
+}
+
+/**
+ * Uninstall from every target directory.
+ *
+ * Non-canonical directories are swept **first**. They hold symlinks pointing at
+ * the canonical copy, so deleting the target before the links turns them into
+ * dangling symlinks that `stat` then reports as absent — leaving the links
+ * themselves on disk.
+ */
+export async function removeSkill(name, targets) {
+  const removed = [];
+  for (const directory of [...targets].reverse()) {
+    const target = path.join(directory, name);
+    if (await removePath(target)) {
+      removed.push(target);
+    }
+  }
+  return removed;
+}
+
+/** `lstat`, not `stat`: a dangling symlink still occupies its path. */
+async function removePath(target) {
+  try {
+    await lstat(target);
+  } catch {
+    return false;
+  }
+  await removeDirectory(target);
+  return true;
+}

package/src/lockfile.mjs

@@ -0,0 +1,74 @@
+import path from "node:path";
+
+import { CliError } from "./utils/errors.mjs";
+import { exists, readJson, writeJson } from "./utils/fs.mjs";
+
+/**
+ * `skills-lock.json` is the same lockfile `npx skills` (vercel-labs) reads and
+ * writes. Matching its v1 shape exactly is deliberate: a project can install
+ * DS-CS skills with `ds-cs add` and third-party skills with `npx skills add`
+ * without the two clobbering each other's state, and `ds-cs list` can report on
+ * skills installed by either tool.
+ *
+ * Shape:
+ *   { "version": 1,
+ *     "skills": { "<skill name>": {
+ *        source, sourceType, skillPath, computedHash } } }
+ */
+export const LOCKFILE_NAME = "skills-lock.json";
+export const LOCKFILE_VERSION = 1;
+
+export function lockfilePath(projectRoot) {
+  return path.join(projectRoot, LOCKFILE_NAME);
+}
+
+export async function readLockfile(projectRoot) {
+  const file = lockfilePath(projectRoot);
+  if (!(await exists(file))) return { version: LOCKFILE_VERSION, skills: {} };
+
+  let parsed;
+  try {
+    parsed = await readJson(file);
+  } catch (error) {
+    throw new CliError(`${LOCKFILE_NAME} is not valid JSON`, {
+      hint: "Fix or delete the file, then re-run.",
+      cause: error,
+    });
+  }
+
+  if (parsed.version !== LOCKFILE_VERSION) {
+    throw new CliError(
+      `${LOCKFILE_NAME} has unsupported version ${JSON.stringify(parsed.version)} (expected ${LOCKFILE_VERSION})`,
+      { hint: "Update the ds-cs CLI, or regenerate the lockfile." }
+    );
+  }
+
+  return { version: LOCKFILE_VERSION, skills: parsed.skills ?? {} };
+}
+
+export async function writeLockfile(projectRoot, lockfile) {
+  const sorted = {};
+  for (const name of Object.keys(lockfile.skills).sort()) {
+    sorted[name] = lockfile.skills[name];
+  }
+  await writeJson(lockfilePath(projectRoot), { version: LOCKFILE_VERSION, skills: sorted });
+}
+
+export async function recordSkill(projectRoot, skill, source) {
+  const lockfile = await readLockfile(projectRoot);
+  lockfile.skills[skill.name] = {
+    source: source.id,
+    sourceType: source.type,
+    skillPath: skill.skillPath,
+    computedHash: skill.hash,
+  };
+  await writeLockfile(projectRoot, lockfile);
+  return lockfile;
+}
+
+export async function forgetSkill(projectRoot, name) {
+  const lockfile = await readLockfile(projectRoot);
+  delete lockfile.skills[name];
+  await writeLockfile(projectRoot, lockfile);
+  return lockfile;
+}

package/src/mcp-config.mjs

@@ -0,0 +1,39 @@
+/**
+ * MCP server config, in the shape each client actually reads.
+ *
+ * OpenCode uses `mcp` rather than `mcpServers` and requires an explicit
+ * `type`, while Claude Code, Cursor, Codex and Windsurf use `mcpServers`. The
+ * difference is not cosmetic — a config with the wrong root key is silently
+ * ignored by the client, which looks exactly like a server that never connects.
+ */
+export const MCP_TARGETS = [
+  { agent: "opencode", file: "opencode.json" },
+  { agent: "claude-code", file: ".mcp.json" },
+  { agent: "cursor", file: ".cursor/mcp.json" },
+  { agent: "codex", file: ".codex/config.json" },
+  { agent: "windsurf", file: ".windsurf/mcp.json" },
+];
+
+export function mcpEndpoint(baseUrl) {
+  return `${baseUrl.replace(/\/+$/, "")}/api/mcp`;
+}
+
+export function buildMcpConfig(agent, url, apiKey) {
+  const endpoint = mcpEndpoint(url);
+  const headers = apiKey ? { Authorization: `Bearer ${apiKey}` } : undefined;
+
+  if (agent === "opencode") {
+    return {
+      $schema: "https://opencode.ai/config.json",
+      mcp: {
+        "ds-cs": { type: "remote", url: endpoint, enabled: true, ...(headers ? { headers } : {}) },
+      },
+    };
+  }
+
+  return {
+    mcpServers: {
+      "ds-cs": { url: endpoint, ...(headers ? { headers } : {}) },
+    },
+  };
+}