@dastyaresocial/ds-cs 0.0.0-stage → 0.1.0

package/skills/product/self-host-deploy/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: self-host-deploy
+description: Install, run, update and back up a self-hosted DS-CS channel with Docker Compose or Vercel. Use for the one-command installer, env var setup, reverse proxying, port layout, backing up the database, or moving a channel to a new version. For writing content use post-with-media.
+---
+
+# Self-hosting DS-CS
+
+## What you need
+
+- Docker and curl
+- A domain with HTTPS (required for browser push notifications)
+- Ports: `8729` (app), `9000` / `9001` (S3 console)
+
+The stack ships Postgres 16 and rustfs (S3-compatible storage) alongside the app. You do not need to provision either.
+
+## Option A — one command
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/dastyare-social/DS-CS/main/scripts/install.sh | bash
+```
+
+Into a specific directory:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/dastyare-social/DS-CS/main/scripts/install.sh -o install.sh
+bash install.sh /opt/ds-cs
+```
+
+The script downloads `docker-compose.yml`, drops in the three editable brand files, creates `.env` with generated secrets if none exists, and starts the stack. It is non-destructive: existing files are left intact rather than overwritten. Compose runs under the pinned project name `ds-cs`, so containers and volumes are prefixed `ds-cs-` regardless of the install directory — two installs cannot collide on volume names.
+
+**Review the generated `.env` before using this in production.** The secrets it writes are locally safe, not production-safe.
+
+## Option B — compose by hand
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/dastyare-social/DS-CS/main/docker-compose.yml -o docker-compose.yml
+cp .env.example .env
+$EDITOR .env
+docker compose up -d
+```
+
+The app container runs migrations and bootstraps the admin user automatically on boot. That is why `db:migrate` runs before `next build` in the build script — schema changes ship as files, never as live database edits.
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `DATABASE_URL` | Postgres connection |
+| `API_KEY` | Shared key for REST writes and MCP write tools |
+| `MCP_API_KEY` | Optional separate key for the stdio MCP server |
+| `BETTER_AUTH_URL`, `BETTER_AUTH_SECRET` | Auth |
+| `ADMIN_EMAIL`, `ADMIN_PASSWORD` | Bootstrap admin, used once |
+| `S3_ENDPOINT`, `S3_REGION`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_BUCKET_NAME`, `S3_FORCE_PATH_STYLE` | Media storage |
+| `S3_PUBLIC_BASE_URL` | Browser-reachable base for media URLs — keep in sync with the published rustfs port |
+| `NEXT_PUBLIC_APP_URL` | Public URL; drives sitemap, canonical URLs and OG images |
+| `NEXT_PUBLIC_WEBPUSH_PUBLIC_KEY`, `WEBPUSH_PRIVATE_KEY`, `WEBPUSH_SUBJECT` | Web Push (VAPID) |
+| `NEXT_PUBLIC_ALLOW_INDEXING` | Unblocks search engines; default blocks indexing |
+| `MEDIA_MAX_*_SIZE_MB`, `MEDIA_ALLOWED_MIME_TYPES` | Upload limits |
+| `NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN`, `POSTHOG_API_KEY` | Analytics |
+
+`NEXT_PUBLIC_APP_URL` being wrong is the most common self-hosting mistake: the sitemap, canonical URLs and OG images are all built from it, so they silently point at localhost.
+
+## Reverse proxy
+
+Terminate TLS at Caddy, nginx or Traefik and proxy to port `8729`. Push notifications require HTTPS — the Service Worker does not register on plain HTTP outside `localhost`.
+
+Also proxy or expose the S3 port if media URLs should be served from your own domain; then set `S3_PUBLIC_BASE_URL` to match. Media served from an unconfigured domain falls back to unoptimized images, which is slower but not broken.
+
+## Vercel
+
+The `Dockerfile.vercel` in the install is a pull-only blueprint (FROM `dastyaresocial/ds-cs:latest` with a PORT-aware CMD) so an installed folder can deploy to Vercel Fluid compute without the app source. Configure the same env vars there. Remember the database and S3 are external services — Vercel does not run your Postgres or rustfs.
+
+## Updating an existing install
+
+```bash
+cd /opt/ds-cs
+docker compose pull
+docker compose up -d
+```
+
+Migrations run on boot. Config files are bind-mounted and read per request, so a config edit does not need an update at all.
+
+## Backups
+
+Two things matter and they live in different places:
+
+```bash
+# database
+docker compose exec -T db pg_dump -U postgres ds-cs > backup.sql
+
+# media
+docker run --rm -v ds-cs_rustfs_data:/data -v "$PWD:/backup" alpine \
+  tar czf /backup/media.tar.gz -C /data .
+```
+
+The media backup volume name follows the pinned project name — confirm it with `docker volume ls | grep rustfs` before assuming. Losing media is not recoverable by re-running the installer; it is the one backup that actually matters.
+
+Restore:
+
+```bash
+docker compose exec -T db psql -U postgres ds-cs < backup.sql
+```
+
+## Verify
+
+```bash
+docker compose ps
+curl -s http://localhost:8729/api/posts?type=count
+curl -s https://your-domain.com/.well-known/mcp
+```
+
+Open the channel, confirm the feed loads, then confirm a media upload round-trips — that exercises the app, Postgres and S3 together.

package/skills/product/webhooks/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: webhooks
+description: Register, inspect and verify signed webhook deliveries from a DS-CS channel. Use for reacting to post and story events, debugging a failing endpoint, or verifying the x-ds-webhook-signature HMAC. For posting content use post-with-media.
+---
+
+# Webhooks
+
+## What it is for
+
+A channel POSTs a signed JSON body to a URL you register whenever something happens. Use it to mirror content into a newsletter, a Discord channel, a cache, or another service — anything that should react to activity without polling.
+
+## Register an endpoint
+
+```bash
+curl -X POST https://cs.example.com/api/webhooks \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://my-app.com/hooks/ds-cs",
+    "events": ["post.created", "post.updated", "post.deleted"]
+  }'
+```
+
+The response contains a **per-endpoint HMAC secret, returned only once**. Store it immediately — it cannot be read back in plaintext later.
+
+```json
+{
+  "id": "…",
+  "url": "https://my-app.com/hooks/ds-cs",
+  "events": ["post.created"],
+  "secret": "whsec_…"
+}
+```
+
+## Events
+
+| Group | Events |
+|---|---|
+| Posts | `post.created`, `post.updated`, `post.deleted`, `post.reacted`, `post.viewed` |
+| Stories | `story.created`, `story.updated`, `story.deleted`, `story.viewed`, `story.liked` |
+
+Subscribe only to what you use — every event is a delivery, and each one is an outbound HTTP request from your channel.
+
+## Delivery payload
+
+```json
+{
+  "id": "<delivery id>",
+  "event": "post.created",
+  "timestamp": "2026-08-23T10:15:00.000Z",
+  "data": { "…": "the post or story record" }
+}
+```
+
+`data` carries the affected record. Verify the signature **before** parsing it.
+
+## Verify the signature — do not skip this
+
+Every delivery has:
+
+```
+x-ds-webhook-signature: t=<unix>,v1=<hex>
+```
+
+`t` is a unix timestamp, `v1` is a lowercase hex HMAC-SHA256. The signed message is the timestamp, a dot, and the **raw request body** — not the parsed JSON:
+
+```js
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export async function POST(request) {
+  const header = request.headers.get("x-ds-webhook-signature") ?? "";
+  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header);
+  if (!match) return new Response("bad signature header", { status: 401 });
+
+  const [, timestamp, provided] = match;
+
+  // Reject replays: anything older than five minutes is not a fresh delivery.
+  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
+  if (age > 300) return new Response("stale delivery", { status: 401 });
+
+  // The raw body — read as text BEFORE any JSON.parse.
+  const raw = await request.text();
+
+  const expected = createHmac("sha256", process.env.DS_CS_WEBHOOK_SECRET)
+    .update(`${timestamp}.${raw}`)
+    .digest("hex");
+
+  const a = Buffer.from(expected, "hex");
+  const b = Buffer.from(provided, "hex");
+  if (a.length !== b.length || !timingSafeEqual(a, b)) {
+    return new Response("invalid signature", { status: 401 });
+  }
+
+  const payload = JSON.parse(raw);
+  // … handle it
+  return new Response("ok", { status: 200 });
+}
+```
+
+Four things that break naive verification:
+
+1. **Sign the raw body.** Re-serializing with `JSON.stringify` changes key order and whitespace, so the HMAC will not match.
+2. **Use the raw request body**, not a framework-parsed object. In Next.js, call `await request.text()` — once. Calling `request.json()` first consumes the stream.
+3. **Compare with `timingSafeEqual`.** A plain `===` leaks the signature byte by byte.
+4. **Check the timestamp.** Without a freshness check, a captured delivery can be replayed forever.
+
+The secret is **per endpoint**, not the channel `API_KEY`. The two are unrelated and never interchangeable.
+
+## Retries and delivery status
+
+Failed deliveries are retried up to three times with backoff. The final failure is recorded.
+
+```bash
+GET /api/webhooks                  # list, with lastStatus / lastAttemptAt / failureCount
+GET /api/webhooks/{webhook_id}     # one endpoint, with delivery status
+```
+
+`failureCount` climbing is the signal to check: is your endpoint returning 2xx fast, or timing out?
+
+## Manage
+
+```bash
+# change URL, events, or pause
+curl -X PATCH https://cs.example.com/api/webhooks/$ID \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"events":["post.created","story.created"],"active":true}'
+
+# pause without deleting
+curl -X PATCH https://cs.example.com/api/webhooks/$ID \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"active":false}'
+
+# delete permanently
+curl -X DELETE https://cs.example.com/api/webhooks/$ID \
+  -H "Authorization: Bearer $API_KEY"
+```
+
+Pausing (`active: false`) stops deliveries but keeps the endpoint and its secret. Deleting removes it and the secret with it.
+
+## Verify locally before going live
+
+```bash
+ngrok http 3000     # or any tunnel
+# register the https URL
+curl -X POST https://cs.example.com/api/webhooks/$ID \
+  -H "Authorization: Bearer $API_KEY" -d '{"events":["post.created"]}'
+# then create a post and watch the tunnel log
+```
+
+Confirm your handler returns 2xx quickly. Slow handlers exhaust the retry budget.
+
+## Mistakes that cost time
+
+- Verifying against the channel `API_KEY` instead of the endpoint secret.
+- `JSON.parse` before `request.text()`, leaving nothing to verify.
+- Skipping the timestamp check and leaving the endpoint replayable.
+- Registering `*.*` and drowning in `post.viewed` deliveries.
+- Treating a 4xx as retryable noise. A 4xx means your handler rejected the event; it will not succeed on retry. Return 2xx for anything you have durably queued, and process asynchronously.

package/src/agents.mjs

@@ -0,0 +1,130 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { CliError } from "./utils/errors.mjs";
+import { exists, isDirectory } from "./utils/fs.mjs";
+
+/**
+ * Where each supported agent looks for project-scoped skills.
+ *
+ * Many agents share `.agents/skills/`, so they are listed as separate names but
+ * resolve to the same directory — installing to one installs to all of them.
+ * This mirrors `npx skills`; entries not listed here can still be targeted with
+ * `--agent-dir <path>`.
+ */
+export const AGENTS = [
+  { name: "opencode", project: ".agents/skills", global: ".config/opencode/skills", detect: ".opencode" },
+  { name: "cursor", project: ".agents/skills", global: ".cursor/skills", detect: ".cursor" },
+  { name: "codex", project: ".agents/skills", global: ".codex/skills", detect: ".codex" },
+  { name: "claude-code", project: ".claude/skills", global: ".claude/skills", detect: ".claude" },
+  { name: "windsurf", project: ".windsurf/skills", global: ".codeium/windsurf/skills", detect: ".windsurf" },
+  { name: "amp", project: ".agents/skills", global: ".config/agents/skills", detect: ".amp" },
+  { name: "gemini-cli", project: ".agents/skills", global: ".gemini/skills", detect: ".gemini" },
+  { name: "github-copilot", project: ".agents/skills", global: ".copilot/skills", detect: ".github" },
+  { name: "goose", project: ".goose/skills", global: ".config/goose/skills", detect: ".goose" },
+  { name: "devin", project: ".devin/skills", global: ".config/devin/skills", detect: ".devin" },
+  { name: "kilo-code", project: ".agents/skills", global: ".kilocode/skills", detect: ".kilocode" },
+  { name: "cline", project: ".agents/skills", global: ".cline/skills", detect: ".cline" },
+  { name: "roo", project: ".roo/skills", global: ".roo/skills", detect: ".roo" },
+  { name: "crush", project: ".crush/skills", global: ".config/crush/skills", detect: ".crush" },
+  { name: "aider-desk", project: ".aider-desk/skills", global: ".aider-desk/skills", detect: ".aider-desk" },
+];
+
+/**
+ * The canonical install location. Everything else either is this directory or
+ * points at it, which keeps a skill's files in exactly one place per project.
+ */
+export const CANONICAL_AGENT = "opencode";
+
+export function getAgent(name) {
+  const agent = AGENTS.find((candidate) => candidate.name === name);
+  if (!agent) {
+    throw new CliError(`Unknown agent "${name}"`, {
+      hint: `Known agents: ${AGENTS.map((candidate) => candidate.name).join(", ")}. Or use --agent-dir <path>.`,
+    });
+  }
+  return agent;
+}
+
+export function skillsDirFor(agentName, { projectRoot, global }) {
+  const agent = getAgent(agentName);
+  const relative = global ? agent.global : agent.project;
+  return global
+    ? path.join(os.homedir(), relative)
+    : path.join(projectRoot, relative);
+}
+
+/**
+ * Agents that look installed in this project (or in the user's home directory).
+ * `ds-cs add` uses this to pre-select targets in interactive mode; with no
+ * detection at all it falls back to the canonical directory.
+ */
+export async function detectAgents({ projectRoot, global }) {
+  const detected = [];
+  for (const agent of AGENTS) {
+    const marker = agent.detect;
+    if (!marker) continue;
+    const projectMarker = path.join(projectRoot, marker);
+    const globalMarker = path.join(os.homedir(), marker);
+    if ((await exists(projectMarker)) || (await exists(globalMarker))) {
+      detected.push(agent.name);
+    }
+  }
+
+  if (detected.length === 0 && !global) {
+    return [CANONICAL_AGENT];
+  }
+  return [...new Set(detected)];
+}
+
+export function dedupeDirectories(directories) {
+  const seen = new Map();
+  for (const directory of directories) {
+    if (!seen.has(directory)) seen.set(directory, directory);
+  }
+  return [...seen.values()];
+}
+
+/**
+ * Install one skill directory into an agent's skills folder.
+ *
+ * Symlink by default: every agent points at the canonical copy, so an update
+ * lands everywhere at once and there is one source of truth. `--copy` is the
+ * escape hatch for filesystems or setups where symlinks do not work.
+ */
+export async function linkSkill(skillDir, skillsDirectory, { copy }) {
+  const target = path.join(skillsDirectory, path.basename(skillDir));
+
+  if (await exists(target)) {
+    await fs.rm(target, { recursive: true, force: true });
+  }
+  await fs.mkdir(skillsDirectory, { recursive: true });
+
+  if (copy) {
+    await fs.cp(skillDir, target, { recursive: true });
+  } else {
+    try {
+      await fs.symlink(path.resolve(skillDir), target, "dir");
+    } catch (error) {
+      // Windows without developer mode, some container mounts, and certain
+      // network filesystems reject symlinks. Copying still produces a correct
+      // install, so degrade instead of failing the whole command.
+      await fs.cp(skillDir, target, { recursive: true });
+      return { target, linked: false, fallbackReason: error.code ?? "symlink unsupported" };
+    }
+  }
+
+  return { target, linked: !copy };
+}
+
+export async function unlinkSkill(name, skillsDirectory) {
+  const target = path.join(skillsDirectory, name);
+  if (!(await exists(target))) return false;
+  await fs.rm(target, { recursive: true, force: true });
+  return true;
+}
+
+export async function skillsDirectoryExists(skillsDirectory) {
+  return isDirectory(skillsDirectory);
+}

package/src/args.mjs

@@ -0,0 +1,111 @@
+/**
+ * Tiny argument parser. Enough for a CLI of this size and nothing more: no
+ * dependency, and unknown flags fail loudly instead of being silently dropped
+ * (a silently-ignored `--global` is worse than an error).
+ */
+
+const ALIASES = {
+  g: "global",
+  a: "agent",
+  s: "skill",
+  y: "yes",
+  l: "list",
+  h: "help",
+  v: "version",
+  p: "project",
+};
+
+/** Flags that take a value. Everything else is treated as boolean. */
+const VALUE_FLAGS = new Set([
+  "agent",
+  "skill",
+  "url",
+  "api-key",
+  "agent-dir",
+  "cwd",
+  "scope",
+]);
+
+export function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === "--") {
+      positional.push(...argv.slice(index + 1));
+      break;
+    }
+
+    if (token.startsWith("--")) {
+      let [name, inlineValue] = splitFlag(token.slice(2));
+      name = ALIASES[name] ?? name;
+
+      if (inlineValue !== undefined) {
+        setFlag(flags, name, inlineValue);
+        continue;
+      }
+
+      const next = argv[index + 1];
+      if (VALUE_FLAGS.has(name)) {
+        if (next === undefined || next.startsWith("-")) {
+          throw new Error(`--${name} needs a value`);
+        }
+        setFlag(flags, name, next);
+        index += 1;
+      } else {
+        flags[name] = true;
+      }
+      continue;
+    }
+
+    if (token.startsWith("-") && token.length > 1) {
+      for (const letter of token.slice(1)) {
+        const name = ALIASES[letter] ?? letter;
+        if (VALUE_FLAGS.has(name)) {
+          const next = argv[index + 1];
+          if (next === undefined || next.startsWith("-")) {
+            throw new Error(`-${letter} needs a value`);
+          }
+          setFlag(flags, name, next);
+          index += 1;
+        } else {
+          flags[name] = true;
+        }
+      }
+      continue;
+    }
+
+    positional.push(token);
+  }
+
+  return { flags, positional };
+}
+
+function splitFlag(text) {
+  const equals = text.indexOf("=");
+  if (equals === -1) return [text, undefined];
+  return [text.slice(0, equals), text.slice(equals + 1)];
+}
+
+function setFlag(flags, name, value) {
+  const key = camelCase(name);
+  if (flags[key] === undefined) {
+    flags[key] = value;
+  } else if (Array.isArray(flags[key])) {
+    flags[key].push(value);
+  } else {
+    flags[key] = [flags[key], value];
+  }
+}
+
+export function camelCase(value) {
+  return value.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+/** Normalise a repeatable flag into an array; `'*'` means "every agent". */
+export function toArray(value) {
+  if (value === undefined) return [];
+  return Array.isArray(value) ? value : [value];
+}

package/src/auth.mjs

@@ -0,0 +1,82 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { CliError } from "./utils/errors.mjs";
+import { exists } from "./utils/fs.mjs";
+
+/**
+ * Channel credentials live in one JSON file outside the project, with owner-only
+ * permissions.
+ *
+ * Keeping them out of the repo is the point: `ds-cs login` stores a key that can
+ * create and delete content, and a project-local config is one `git add -A` away
+ * from being published.
+ */
+export function configPath() {
+  const base =
+    process.env.DS_CS_CONFIG_DIR ??
+    (process.env.XDG_CONFIG_HOME
+      ? path.join(process.env.XDG_CONFIG_HOME, "ds-cs")
+      : path.join(os.homedir(), ".config", "ds-cs"));
+  return path.join(base, "auth.json");
+}
+
+export async function readAuth() {
+  const file = configPath();
+  if (!(await exists(file))) return { baseUrl: null, apiKey: null, loggedInAt: null };
+  try {
+    const parsed = JSON.parse(await fs.readFile(file, "utf8"));
+    return {
+      baseUrl: parsed.baseUrl ?? null,
+      apiKey: parsed.apiKey ?? null,
+      loggedInAt: parsed.loggedInAt ?? null,
+    };
+  } catch (error) {
+    throw new CliError(`Auth config at ${file} is not valid JSON`, {
+      hint: "Run `ds-cs logout` to clear it.",
+      cause: error,
+    });
+  }
+}
+
+export async function writeAuth({ baseUrl, apiKey }) {
+  const file = configPath();
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(
+    file,
+    `${JSON.stringify({ baseUrl, apiKey, loggedInAt: new Date().toISOString() }, null, 2)}\n`,
+    { encoding: "utf8", mode: 0o600 }
+  );
+  // Write with the mode, but also force it: an existing file keeps its old bits
+  // across a rewrite on some platforms.
+  await fs.chmod(file, 0o600).catch(() => {});
+  return file;
+}
+
+export async function clearAuth() {
+  const file = configPath();
+  if (!(await exists(file))) return false;
+  await fs.rm(file);
+  return true;
+}
+
+/** Resolve the channel URL for a command: flag, then stored login, then env. */
+export async function resolveTarget({ url: urlFlag } = {}) {
+  const stored = await readAuth();
+  const baseUrl = (urlFlag ?? stored.baseUrl ?? process.env.DS_CS_URL ?? "").trim();
+  const apiKey = (stored.apiKey ?? process.env.DS_CS_API_KEY ?? "").trim();
+
+  if (!baseUrl) {
+    throw new CliError("No channel URL configured", {
+      hint: "Run `ds-cs login --url https://your-channel.com --api-key <key>`, or pass --url.",
+    });
+  }
+
+  return { baseUrl: baseUrl.replace(/\/+$/, ""), apiKey, stored };
+}
+
+export function redact(apiKey) {
+  if (!apiKey) return "";
+  return apiKey.length <= 8 ? "***" : `${apiKey.slice(0, 4)}…${apiKey.slice(-4)}`;
+}