@dastyaresocial/ds-cs 0.0.0-stage → 0.1.0

package/src/commands/add.mjs

@@ -0,0 +1,118 @@
+import path from "node:path";
+
+import {
+  CANONICAL_AGENT,
+  dedupeDirectories,
+  detectAgents,
+  getAgent,
+  skillsDirFor,
+} from "../agents.mjs";
+import { installSkills } from "../install.mjs";
+import { lockfilePath } from "../lockfile.mjs";
+import { discoverSkills } from "../skills/discover.mjs";
+import { toArray } from "../args.mjs";
+import { CliError } from "../utils/errors.mjs";
+import { cyan, log, table } from "../utils/log.mjs";
+import { resolveRequest } from "./target.mjs";
+
+export async function addCommand(positional, flags, { projectRoot }) {
+  const { source, names } = resolveRequest(positional, flags);
+
+  if (flags.list) {
+    await listSource(source, projectRoot);
+    return;
+  }
+
+  const global = Boolean(flags.global);
+  const targets = resolveTargets(flags, { projectRoot, global });
+
+  const { installed, resolved } = await installSkills({
+    source,
+    names,
+    projectRoot,
+    targets,
+    global,
+    copy: Boolean(flags.copy),
+    yes: Boolean(flags.yes),
+  });
+
+  log.success(`Installed ${installed.length} skill${installed.length === 1 ? "" : "s"} from ${resolved.describe()}`);
+
+  for (const entry of installed) {
+    log.plain(`  ${cyan(entry.skill.name)}  ${entry.skill.description}`);
+    log.plain(`    ${display(entry.destination)}`);
+    for (const link of entry.links) {
+      log.plain(`    → ${display(link.target)} (${link.linked ? "linked" : "copied — symlinks unavailable"})`);
+    }
+  }
+
+  log.plain(`\n  Recorded in ${display(lockfilePath(projectRoot))}`);
+}
+
+/**
+ * Show paths relative to the current directory, but fall back to absolute when
+ * the relative form would be a chain of `../` — nobody can place that.
+ */
+function display(target) {
+  const relative = path.relative(process.cwd(), target);
+  return relative === "" || relative.startsWith("..") ? target : relative;
+}
+
+async function listSource(sourceSpec, projectRoot) {
+  const { resolveSource } = await import("../registry/sources.mjs");
+  const resolved = await resolveSource(sourceSpec, { cwd: projectRoot });
+  const skills = (await discoverSkills(resolved.root)).filter(
+    (skill) => process.env.INSTALL_INTERNAL_SKILLS === "1" || !skill.internal
+  );
+
+  if (skills.length === 0) {
+    log.warn(`No skills found in ${resolved.describe()}`);
+    return;
+  }
+
+  log.info(`Skills in ${resolved.describe()}:\n`);
+  table(
+    skills.map((skill) => ({
+      name: skill.name,
+      path: skill.skillPath.replace(/SKILL\.md$/, ""),
+      description: skill.description,
+    })),
+    [
+      { key: "name", title: "NAME" },
+      { key: "path", title: "PATH" },
+      { key: "description", title: "DESCRIPTION", flex: true },
+    ]
+  );
+}
+
+function resolveTargets(flags, { projectRoot, global }) {
+  const requested = toArray(flags.agent);
+  if (requested.includes("*")) return [canonicalDir(projectRoot, global)];
+
+  if (requested.length === 0) {
+    return detectAgents({ projectRoot, global }).then((agents) =>
+      dedupeDirectories(
+        agents.map((agent) => skillsDirFor(agent, { projectRoot, global }))
+      )
+    );
+  }
+
+  return requested.map((name) => {
+    try {
+      return skillsDirFor(getAgent(name).name, { projectRoot, global });
+    } catch {
+      // `--agent` accepts a literal directory too, so an agent this CLI does not
+      // know about can still be targeted without waiting to be added here.
+      if (name.startsWith(".") || path.isAbsolute(name)) {
+        return path.isAbsolute(name) ? name : path.join(projectRoot, name);
+      }
+      throw new CliError(`Unknown agent "${name}"`, {
+        hint: "Run `ds-cs init --list-agents`, or pass a directory starting with \".\" or \"/\".",
+      });
+    }
+  });
+}
+
+function canonicalDir(projectRoot, global) {
+  return skillsDirFor(CANONICAL_AGENT, { projectRoot, global });
+}

package/src/commands/auth.mjs

@@ -0,0 +1,87 @@
+import { clearAuth, configPath, readAuth, redact, writeAuth } from "../auth.mjs";
+import { CliError } from "../utils/errors.mjs";
+import { log } from "../utils/log.mjs";
+import { promptText } from "../utils/prompt.mjs";
+
+/**
+ * Store channel credentials and prove they work before saving them.
+ *
+ * The verification matters: an API key typed from memory is often wrong, and
+ * discovering that at the first `create_post` — inside an agent, mid-task — is a
+ * much worse place to find out than at login.
+ */
+export async function loginCommand(positional, flags) {
+  const baseUrl =
+    flags.url ??
+    positional[0] ??
+    process.env.DS_CS_URL ??
+    (await readAuth()).baseUrl ??
+    (await promptText("Channel URL:", "https://cs.dastyare.social"));
+
+  if (!baseUrl) {
+    throw new CliError("A channel URL is required", { hint: "Pass --url https://your-channel.com" });
+  }
+
+  const normalized = baseUrl.replace(/\/+$/, "");
+  const apiKey = flags.apiKey ?? (await promptText("API key (blank for read-only):", ""));
+
+  await verify(normalized, apiKey);
+
+  const file = await writeAuth({ baseUrl: normalized, apiKey: apiKey || null });
+
+  log.success(`Logged in to ${normalized}`);
+  if (apiKey) {
+    log.info(`  key   ${redact(apiKey)}`);
+  } else {
+    log.warn("  no API key stored — read tools only");
+  }
+  log.info(`  saved ${file} (mode 0600)`);
+}
+
+async function verify(baseUrl, apiKey) {
+  const headers = apiKey ? { authorization: `Bearer ${apiKey}` } : {};
+  let response;
+  try {
+    response = await fetch(`${baseUrl}/api/posts?type=count`, { headers });
+  } catch (error) {
+    throw new CliError(`Could not reach ${baseUrl}`, {
+      hint: "Check the URL and that the channel is running.",
+      cause: error,
+    });
+  }
+
+  if (response.status === 401 || response.status === 403) {
+    throw new CliError(`${baseUrl} rejected the API key`, {
+      hint: "The key is the API_KEY from your channel's .env. Read access needs no key.",
+    });
+  }
+  if (!response.ok) {
+    throw new CliError(`${baseUrl} returned ${response.status} ${response.statusText}`);
+  }
+
+  const body = await response.json().catch(() => null);
+  log.info(`  connected — ${body?.total ?? "?"} posts visible`);
+}
+
+export async function whoamiCommand() {
+  const stored = await readAuth();
+
+  if (!stored.baseUrl) {
+    log.info("Not logged in. Run `ds-cs login --url https://your-channel.com`.");
+    log.info(`  (credentials would live in ${configPath()})`);
+    return;
+  }
+
+  log.info(`Channel  ${stored.baseUrl}`);
+  log.info(`API key  ${stored.apiKey ? redact(stored.apiKey) : "none (read-only)"}`);
+  if (stored.loggedInAt) log.info(`Since    ${stored.loggedInAt}`);
+}
+
+export async function logoutCommand() {
+  const removed = await clearAuth();
+  if (removed) {
+    log.success(`Removed ${configPath()}`);
+  } else {
+    log.info("No stored credentials to remove.");
+  }
+}

package/src/commands/init.mjs

@@ -0,0 +1,106 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { CANONICAL_AGENT, detectAgents, skillsDirFor } from "../agents.mjs";
+import { toArray } from "../args.mjs";
+import { MCP_TARGETS, buildMcpConfig } from "../mcp-config.mjs";
+import { exists, ensureDir } from "../utils/fs.mjs";
+import { cyan, log } from "../utils/log.mjs";
+import { printAgents } from "./list.mjs";
+
+const GITIGNORE_BLOCK = `# ds-cs
+# Skills installed by \`ds-cs add\` are meant to be committed: they are project
+# context, shared with the team, the same way source is. Add .agents/ here only
+# if you want every agent's skills to stay local to one machine.
+`;
+
+/**
+ * Prepare a project for DS-CS skills.
+ *
+ * `init` deliberately installs nothing by itself. It creates the directories and
+ * optionally the MCP wiring, then prints what to run next — a new user who has
+ * not asked for a specific skill should not silently end up with forty of them
+ * in their repository.
+ */
+export async function initCommand(positional, flags, { projectRoot }) {
+  if (flags.listAgents) {
+    printAgents();
+    return;
+  }
+
+  const global = Boolean(flags.global);
+  const detected = await detectAgents({ projectRoot, global });
+  const requested = toArray(flags.agent);
+  const agents = requested.length > 0 ? requested : detected;
+
+  for (const agent of agents) {
+    const directory = skillsDirFor(agent, { projectRoot, global });
+    await ensureDir(directory);
+  }
+
+  // Many agents share one directory (OpenCode, Cursor and Codex all read
+  // `.agents/skills`), so report each real directory once.
+  for (const directory of new Set(agents.map((agent) => skillsDirFor(agent, { projectRoot, global })))) {
+    log.success(`Skills directory ready: ${display(directory)}`);
+  }
+
+  if (!global) {
+    await explainGitignore(projectRoot);
+  }
+
+  if (flags.mcp) {
+    await writeMcpConfigs(projectRoot, flags);
+  }
+
+  log.plain("");
+  log.plain(`Next: ${cyan("ds-cs add")} to install skills.`);
+  log.plain(`  ${cyan("ds-cs add")}                    browse the DS-CS registry`);
+  log.plain(`  ${cyan("ds-cs add brand-config")}         install one skill by name`);
+  log.plain(`  ${cyan("ds-cs add owner/repo@skill")}     install from any GitHub skills repo`);
+}
+
+function display(target) {
+  return path.relative(process.cwd(), target) || ".";
+}
+
+/**
+ * ds-cs skills are meant to be committed, so this writes no ignore rule by
+ * default — it only leaves a comment explaining the choice, and warns if the
+ * project already excludes them.
+ */
+async function explainGitignore(projectRoot) {
+  const file = path.join(projectRoot, ".gitignore");
+
+  if (!(await exists(file))) {
+    await fs.writeFile(file, GITIGNORE_BLOCK, "utf8");
+    log.success("Created .gitignore explaining that ds-cs skills are meant to be committed");
+    return;
+  }
+
+  const existing = await fs.readFile(file, "utf8");
+  if (/^\/?\.agents\/?\s*$/m.test(existing)) {
+    log.warn(".gitignore excludes .agents — skills will not be shared with your team");
+  }
+}
+
+async function writeMcpConfigs(projectRoot, flags) {
+  const url = flags.url ?? "https://cs.dastyare.social";
+
+  for (const target of MCP_TARGETS) {
+    const file = path.join(projectRoot, target.file);
+    if (await exists(file)) {
+      log.warn(`Skipped ${display(file)} — it already exists`);
+      continue;
+    }
+
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(
+      file,
+      `${JSON.stringify(buildMcpConfig(target.agent, url, flags.apiKey), null, 2)}\n`,
+      "utf8"
+    );
+    log.success(`MCP server "ds-cs" written to ${display(file)}`);
+  }
+}
+
+export { CANONICAL_AGENT };

package/src/commands/list.mjs

@@ -0,0 +1,89 @@
+import path from "node:path";
+
+import { AGENTS, CANONICAL_AGENT, skillsDirFor } from "../agents.mjs";
+import { readLockfile } from "../lockfile.mjs";
+import { readSkillManifest } from "../skills/frontmatter.mjs";
+import { isFile } from "../utils/fs.mjs";
+import { dim, log, table } from "../utils/log.mjs";
+
+/**
+ * Report what is installed.
+ *
+ * The lockfile is the source of truth for *what was asked for*; the filesystem is
+ * checked to show what actually survived. Those two can disagree — someone can
+ * delete a skill directory by hand — and an inventory that hides that is worse
+ * than useless.
+ */
+export async function listCommand(positional, flags, { projectRoot }) {
+  const global = Boolean(flags.global);
+  const lockfile = await readLockfile(projectRoot);
+  const names = Object.keys(lockfile.skills).sort();
+
+  const filter = positional[0];
+
+  if (names.length === 0) {
+    log.info(
+      global
+        ? "No skills installed globally."
+        : `No skills installed in this project. Try \`ds-cs add\` or run \`ds-cs init\`.`
+    );
+    return;
+  }
+
+  const rows = [];
+  for (const name of names) {
+    if (filter && !name.includes(filter)) continue;
+    const entry = lockfile.skills[name];
+    const installed = await readInstalledSkill(projectRoot, name, global);
+
+    rows.push({
+      name,
+      source: entry.source,
+      path: entry.skillPath,
+      status: installed ? "installed" : "MISSING",
+      description: installed?.description ?? "",
+    });
+  }
+
+  if (rows.length === 0) {
+    log.info(`No installed skill matches "${filter}".`);
+    return;
+  }
+
+  table(rows, [
+    { key: "name", title: "NAME" },
+    { key: "status", title: "STATUS" },
+    { key: "source", title: "SOURCE" },
+    { key: "description", title: "DESCRIPTION", flex: true },
+  ]);
+
+  const missing = rows.filter((row) => row.status === "MISSING");
+  if (missing.length > 0) {
+    log.plain("");
+    log.warn(
+      `${missing.length} skill${missing.length === 1 ? "" : "s"} recorded in ${path.basename("skills-lock.json")} but not on disk: ${missing.map((row) => row.name).join(", ")}`
+    );
+    log.plain(dim("Run `ds-cs add <name>` to reinstall."));
+  }
+}
+
+async function readInstalledSkill(projectRoot, name, global) {
+  const skillFile = path.join(
+    skillsDirFor(CANONICAL_AGENT, { projectRoot, global }),
+    name,
+    "SKILL.md"
+  );
+  if (!(await isFile(skillFile))) return null;
+  return readSkillManifest(skillFile);
+}
+
+export function printAgents() {
+  table(
+    AGENTS.map((agent) => ({ name: agent.name, project: agent.project, global: agent.global })),
+    [
+      { key: "name", title: "AGENT" },
+      { key: "project", title: "PROJECT PATH" },
+      { key: "global", title: "GLOBAL PATH" },
+    ]
+  );
+}

package/src/commands/mcp.mjs

@@ -0,0 +1,101 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { readAuth, redact } from "../auth.mjs";
+import { MCP_TARGETS, buildMcpConfig, mcpEndpoint } from "../mcp-config.mjs";
+import { exists } from "../utils/fs.mjs";
+import { cyan, log } from "../utils/log.mjs";
+
+/**
+ * Print — and optionally write — the MCP server config for a channel.
+ *
+ * Every format is printed by default and only the named agent's file is
+ * written. An existing config is never overwritten: the snippet is shown so the
+ * user can merge it, because clobbering a working MCP config to add one server
+ * is a bad trade.
+ */
+export async function mcpCommand(positional, flags, { projectRoot }) {
+  const stored = await readAuth();
+  const url = (flags.url ?? stored.baseUrl ?? "https://cs.dastyare.social").replace(/\/+$/, "");
+  const apiKey = flags.apiKey ?? stored.apiKey ?? null;
+  const endpoint = mcpEndpoint(url);
+
+  const headers = apiKey ? { Authorization: `Bearer ${apiKey}` } : undefined;
+
+  const snippets = [
+    {
+      name: "Remote (recommended)",
+      note: "Works for every MCP client. No local process.",
+      configs: {
+        "Claude Desktop / Cursor / generic": buildMcpConfig("claude-code", url, apiKey),
+        "Claude Code": {
+          mcpServers: {
+            "ds-cs": { type: "url", url: endpoint, ...(headers ? { headers } : {}) },
+          },
+        },
+        OpenCode: buildMcpConfig("opencode", url, apiKey),
+      },
+    },
+    {
+      name: "Local (stdio, needs a clone)",
+      note: "Faster and works offline. Requires DATABASE_URL and the repo.",
+      configs: {
+        "Claude Code / Cursor": {
+          mcpServers: {
+            "ds-cs": { command: "bun", args: ["run", "mcp"], cwd: "<path-to-ds-cs-repo>" },
+          },
+        },
+      },
+    },
+  ];
+
+  for (const section of snippets) {
+    log.plain(`\n${section.name} — ${section.note}`);
+    for (const [label, config] of Object.entries(section.configs)) {
+      log.plain(`\n  ${label}:`);
+      log.plain(indent(JSON.stringify(config, null, 2)));
+    }
+  }
+
+  if (apiKey) {
+    log.plain(`\n  Using API key ${cyan(redact(apiKey))} (write access enabled)`);
+  } else {
+    log.plain("\n  No API key configured — read tools only. Run `ds-cs login` for write access.");
+  }
+
+  const writeTarget = positional[0];
+  if (writeTarget) {
+    await writeConfig(projectRoot, writeTarget, url, apiKey);
+  }
+}
+
+function indent(text) {
+  return text
+    .split("\n")
+    .map((line) => `    ${line}`)
+    .join("\n");
+}
+
+async function writeConfig(projectRoot, agent, url, apiKey) {
+  const target = MCP_TARGETS.find((candidate) => candidate.agent === agent);
+  if (!target) {
+    log.warn(
+      `Unknown agent "${agent}" — nothing written. Valid: ${MCP_TARGETS.map((c) => c.agent).join(", ")}`
+    );
+    return;
+  }
+
+  const file = path.join(projectRoot, target.file);
+  if (await exists(file)) {
+    log.warn(`${target.file} already exists — not overwritten. Merge the snippet manually.`);
+    return;
+  }
+
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(
+    file,
+    `${JSON.stringify(buildMcpConfig(agent, url, apiKey), null, 2)}\n`,
+    "utf8"
+  );
+  log.success(`\nWrote ${target.file}`);
+}

package/src/commands/remove.mjs

@@ -0,0 +1,80 @@
+import path from "node:path";
+
+import { CANONICAL_AGENT, skillsDirFor } from "../agents.mjs";
+import { forgetSkill, readLockfile } from "../lockfile.mjs";
+import { removeSkill } from "../install.mjs";
+import { toArray } from "../args.mjs";
+import { ensureDir } from "../utils/fs.mjs";
+import { log } from "../utils/log.mjs";
+import { select } from "../utils/prompt.mjs";
+
+/**
+ * Uninstall skills.
+ *
+ * Removing from the canonical directory alone would leave the symlinks in other
+ * agents' directories dangling, so every configured target is swept.
+ */
+export async function removeCommand(positional, flags, { projectRoot }) {
+  const global = Boolean(flags.global);
+  const lockfile = await readLockfile(projectRoot);
+  const installed = Object.keys(lockfile.skills).sort();
+
+  let names = [...positional.flatMap(splitCommas), ...toArray(flags.skill)];
+
+  if (names.includes("*") || names.length === 0) {
+    if (installed.length === 0) {
+      log.info("Nothing to remove.");
+      return;
+    }
+    if (flags.all) {
+      names = installed;
+    } else {
+      const picked = await select("Which skills should be removed?", installed.map((name) => ({
+        label: name,
+        value: name,
+      })));
+      names = picked.map((choice) => choice.value);
+      if (names.length === 0) return;
+    }
+  }
+
+  const unknown = names.filter((name) => !lockfile.skills[name]);
+  const targets = await agentDirectories(projectRoot, flags, global);
+
+  for (const directory of targets) {
+    await ensureDir(directory);
+  }
+
+  for (const name of names) {
+    const removed = await removeSkill(name, targets);
+    await forgetSkill(projectRoot, name);
+
+    if (unknown.includes(name)) {
+      log.warn(`"${name}" was not in the lockfile; removed ${removed.length} file(s) from disk`);
+      continue;
+    }
+    log.success(`Removed ${name} from ${removed.length} location(s)`);
+  }
+
+  log.plain(`\n  ${path.relative(process.cwd(), path.join(projectRoot, "skills-lock.json"))} updated`);
+}
+
+function splitCommas(value) {
+  return value.includes(",") ? value.split(",").map((name) => name.trim()) : [value];
+}
+
+async function agentDirectories(projectRoot, flags, global) {
+  const canonical = skillsDirFor(CANONICAL_AGENT, { projectRoot, global });
+  const requested = toArray(flags.agent);
+  if (requested.length === 0 || requested.includes("*")) return [canonical];
+
+  const directories = [canonical];
+  for (const agent of requested) {
+    if (agent.startsWith(".") || path.isAbsolute(agent)) {
+      directories.push(path.isAbsolute(agent) ? agent : path.join(projectRoot, agent));
+    } else {
+      directories.push(skillsDirFor(agent, { projectRoot, global }));
+    }
+  }
+  return [...new Set(directories)];
+}

package/src/commands/search.mjs

@@ -0,0 +1,51 @@
+import { CANONICAL_AGENT, skillsDirFor } from "../agents.mjs";
+import { readLockfile } from "../lockfile.mjs";
+import { listInstalledSkills } from "../skills/discover.mjs";
+import { log, table } from "../utils/log.mjs";
+
+/**
+ * Search installed skills by name and description.
+ *
+ * Offline by design: it walks the skills that are actually installed rather than
+ * reaching for a registry. `ds-cs add <source> --list` is the command for
+ * browsing a source you have not installed from yet.
+ */
+export async function searchCommand(positional, flags, { projectRoot }) {
+  const query = (positional.join(" ") || "").toLowerCase();
+  const lockfile = await readLockfile(projectRoot);
+
+  const canonical = skillsDirFor(CANONICAL_AGENT, {
+    projectRoot,
+    global: Boolean(flags.global),
+  });
+
+  const available = await listInstalledSkills(canonical);
+  if (available.length === 0) {
+    log.info("No skills installed in this project.");
+    return;
+  }
+  const matches = available
+    .filter((skill) => {
+      if (query === "") return true;
+      return (
+        skill.name.toLowerCase().includes(query) ||
+        skill.description.toLowerCase().includes(query)
+      );
+    })
+    .map((skill) => ({
+      name: skill.name,
+      source: lockfile.skills[skill.name]?.source ?? "(local)",
+      description: skill.description,
+    }));
+
+  if (matches.length === 0) {
+    log.info(query === "" ? "No skills installed." : `No installed skill matches "${query}".`);
+    return;
+  }
+
+  table(matches, [
+    { key: "name", title: "NAME" },
+    { key: "source", title: "SOURCE" },
+    { key: "description", title: "DESCRIPTION", flex: true },
+  ]);
+}