@tianshu-ai/tianshu 0.3.0

package/packages/server/builtinConfig/plugins/workboard/skills/worker-fleet.md

@@ -0,0 +1,431 @@
+---
+name: worker-fleet
+description: How to design a multi-worker fleet for a non-trivial user request. Read this when the user asks for something that has natural separation of concerns (research → write, design → build → test, scrape → analyse → report) and a single worker would either lose context or do all roles badly. Covers role decomposition, SOUL.md authoring per role, task DAG design, and failure handling.
+scope: main
+---
+
+# Designing a worker fleet
+
+When the user gives you a non-trivial goal, your default is to be
+boring: drop one task, let `llm-default` handle it. That works for
+small, single-axis requests.
+
+This skill is for when it doesn't. Three signals say "fleet":
+
+1. **Multiple distinct roles.** "Design then build then test" is
+   three roles; bundling them into one prompt makes the agent
+   skim the spec because it's also writing code in the same turn.
+2. **Quality matters across boundaries.** A coder who also writes
+   docs writes mediocre docs; a writer who also picks the model
+   architecture picks the wrong one. Boundaries enforce focus.
+3. **Sequential dependency you can name.** If you can draw an
+   arrow ("the next agent reads what the previous one wrote"),
+   the arrow exists in the worker_agents pool too — make it
+   explicit via task `depends_on` instead of hand-holding.
+
+If none of those apply, **don't build a fleet** — overhead
+without payoff.
+
+## Default phase pipeline: plan → design → build → verify
+
+For non-trivial deliverables, decompose into phases BEFORE
+creating any task. The default pipeline:
+
+| Phase | What it produces |
+|---|---|
+| **PLAN** | Clarified requirements, sketched approach, listed assumptions, open questions answered. Output is usually a short markdown brief at `./projects/<slug>/PLAN.md`. |
+| **DESIGN** | Concrete data shapes, file layout, interfaces, technology choices with rationale. Output is `DESIGN.md` plus any scaffolding files. |
+| **BUILD** | The actual implementation. May be one task or several (see Sizing below). Output is the artefact at its final path. |
+| **VERIFY** | Runs the artefact end-to-end against the acceptance criteria from PLAN. Captures evidence (test output, screenshot, file size, etc). Stamps a one-line verdict on the task. |
+
+Each phase is **one task** (or BUILD may split into BUILD-1/2/3 —
+see Sizing). Wire `dependsOn` so phase N+1 doesn't start until
+phase N is done.
+
+Skip phases only when the work genuinely doesn't need them: a
+one-off bug fix can go straight to BUILD + VERIFY; a research
+request may collapse to PLAN + BUILD where BUILD is the report
+itself.
+
+The phase pipeline is what makes the kanban useful for the user
+— they see PLAN done, can review the approach, then watch BUILD
+turn over without you holding their hand on every commit.
+
+## Reuse over create (read this twice)
+
+Before creating any new worker, run:
+
+```
+tenant_config_list({ path: "workers" })
+```
+
+For every role you think you need, ask in this order:
+
+1. **Does an existing worker fit?** Match by responsibility, not
+   by name. The `coder` worker is a generalist code writer —
+   reuse it instead of inventing `frontend-dev` / `backend-dev`
+   / `python-coder` siblings. The `llm-default` worker is a
+   generalist for everything that doesn't need a sharper SOUL.
+2. **Can the existing worker do this with a clearer task
+   description?** Most "bad" outputs are bad task descriptions,
+   not wrong workers. Tighten the description first.
+3. **Can a small SOUL.md edit on the existing worker absorb the
+   new role?** If the new role is a 20% twist on an existing
+   one, edit `tenant_config_write workers/<slug>/SOUL.md`
+   instead of forking.
+4. **Only when 1–3 fail or the user explicitly asked for a new
+   worker** — build the new one.
+
+Proliferating workers is the most common over-engineering trap.
+Three consequences if you do it anyway:
+
+- Each new SOUL is one more thing to maintain when behaviour
+  drifts.
+- The user sees more rows in the Worker agents page than they
+  needed; the cognitive load is on them, not you.
+- Identity collisions get more likely (a `writer` and a
+  `content-writer` confuse both the user and future you).
+
+Ack the reuse decision out loud to the user when you make it:
+"I'll use the existing `coder` worker for the build step — it
+fits." That gives them a chance to override ("actually I want
+a separate `coder-typescript` for this project") before you
+commit.
+
+## When NOT to fleet (just as important)
+
+- One-shot Q&A, retrieval, or chat-as-thinking — main agent.
+- Anything ≤ 5 minutes single-worker — overhead > payoff.
+- Tasks where the "different roles" are actually the same person
+  doing different *steps* (e.g. "first research, then write the
+  same report"). Use one worker with a clearer SOUL instead.
+- Throwaway / prototype work the user will rewrite anyway.
+
+## Sizing (and the max_tokens stall trap)
+
+Keep each task small enough that one worker can finish it in one
+focused run — a few tool calls, a few files, one chunk of
+reasoning. The worst failure mode in this system is a task that
+generates so much content the LLM hits its `max_tokens` cap
+mid-flight, runs out of room to call `task_complete`, and the
+worker pool marks it stalled. The output you produced before the
+cutoff is usually wasted, because the next attempt restarts from
+the original task description.
+
+Concrete signals that a task is too big and should split:
+
+- generates 1000+ lines of code in one go
+- needs 10+ separate tool calls in one task
+- the user-visible deliverable has clear sub-features that ship
+  independently (\"the editor\" + \"the preview\" + \"the save/load\")
+- you'd struggle to write a one-paragraph spec for it without
+  resorting to bullet lists with many items
+
+When any of those apply, split: BUILD-1 (scaffolding + first
+feature), BUILD-2 (next feature, depends on BUILD-1), and so on.
+Many small tasks compose, retry better when one fails, surface
+progress on the kanban, and let you intervene per-step instead
+of per-monolith.
+
+## Sizing
+
+- **2 workers** is the common case. (designer + builder), (writer
+  + editor), (researcher + summariser).
+- **3 workers** when you want a third pair of eyes — typically a
+  QA / reviewer / critic at the end. Most "design → build → test"
+  flows want 3.
+- **4+ workers** is rare. Don't introduce a worker just because a
+  *file type* is different (one md writer, one py writer); split
+  on *responsibility*, not output format.
+
+If you're tempted to use 5+, you're probably modelling a function
+call graph as a fleet — collapse the small ones into a single
+worker that runs them sequentially.
+
+## Designing each role
+
+For every worker you propose:
+
+1. **Name the responsibility in one sentence.** "Designs the
+   API spec, writes no code." If the sentence has an "and"
+   that's not just fluff, split into two roles.
+2. **List inputs and outputs explicitly.** What files does the
+   worker read? What files does it produce? Path conventions
+   below.
+3. **Anti-list the role.** What is the worker NOT supposed to
+   do? "Don't read source files", "don't run tests", "don't
+   add features the spec doesn't mention". This goes in SOUL.md.
+4. **Pick a kind + model.** `kind: "llm"` for everything LLM-
+   shaped (the `kind` field is a runtime, not a label — see
+   worker-creator). Model defaults to host default; only set
+   `modelId` if the role genuinely needs Sonnet / Opus / etc.
+5. **Decide allow-lists.** Default = omit toolsAllow /
+   skillsAllow. Only narrow when the role *should* be sandboxed
+   (e.g. a "summariser" worker that should only read, never
+   write).
+
+## SOUL.md template
+
+Open with the role identity, then state the boundaries the
+*role* needs (the global SOUL set by the Default LLM is gone
+when this worker runs, so cover the basics yourself):
+
+```
+You are <role>, a workboard worker focused on <one-sentence
+responsibility>.
+
+## Your job
+
+- <2-4 bullet points on what you DO>
+
+## Your boundaries
+
+- <2-4 bullet points on what you DO NOT do>
+- <Mention sibling workers' roles so it doesn't try to do their job>
+
+## Inputs / outputs
+
+- Read: <explicit paths or "the description tells you">
+- Produce: <explicit paths under ./projects/<slug>/>
+
+## Exit contract
+
+Call task_complete with a one-line summary of what you produced
+and a `files` array listing every file you wrote. The orchestrator
+only sees this summary — narrative replies don't reach it.
+```
+
+Keep it under 40 lines. Workers don't need a manifesto, they need
+a contract.
+
+## Path conventions
+
+Pick a single project slug for the whole fleet's outputs and put
+everything under `./projects/<slug>/`:
+
+```
+./projects/<slug>/
+├── spec.md            <- architect's output
+├── server.js          <- coder's output
+├── server.test.js
+├── README.md
+├── qa-report.md       <- qa's output
+└── (anything else workers produce)
+```
+
+Every task description tells its worker:
+- exactly which sibling-produced files to read (full path), and
+- exactly which files to produce (full path).
+
+This is what makes the fleet composable: workers don't need to
+know each other exists, only the file contract.
+
+## Task DAG
+
+One task per worker, normally. Use `depends_on` to express the
+arrow:
+
+```
+T1 (architect)       — no deps, picked up immediately
+T2 (coder)           — depends_on: [T1.id]
+T3 (qa)              — depends_on: [T2.id]
+```
+
+Pool semantics:
+- `task_create` returns the new task's `id`. Capture it before
+  creating the dependent task.
+- A blocked task stays in `ready` with a lock chip; the pool
+  skips it until every dep reaches `done`.
+- Same-priority tasks claimed in created-order; bump `priority`
+  on the latest task only when you really need it ahead.
+
+For *parallel* fan-out (e.g. one researcher feeds three
+writers), you write three siblings all `depends_on: [T1.id]`.
+Don't try to fan-in — workers can't talk to each other; if the
+output needs aggregation, that's a fourth worker reading the
+three siblings' outputs.
+
+## Task description checklist
+
+A good task description always has:
+
+1. **Goal in one sentence** — what file(s) the worker writes.
+2. **What to read** — full paths, named, `tenant_config_read`-
+   able. Describe what's in those files briefly so the worker
+   knows what to look for.
+3. **What to produce** — full paths, format constraints (e.g.
+   "JSON", "markdown with front-matter").
+4. **Quality gate** — measurable criteria. Tests pass? At least
+   N test cases? Output validates against schema? Lints clean?
+   Whatever the role's "self-verify" looks like.
+5. **Boundaries restated** — "don't add features the spec
+   doesn't mention", "don't read source files".
+
+If the description fits in two sentences, the task is too small
+or too vague — either inline it (don't fleet at all) or split
+it into more concrete subtasks.
+
+## When the task ingests / produces a lot
+
+If a task asks the worker to read ≥ 2 non-trivial files **and**
+produce a single large output (long HTML / md / generated
+code), you've crossed the threshold where naive prompting
+breaks: the worker batches all the reads into one turn, the
+tool results dominate the prompt, and the next call returns
+empty (`no_completion`).
+
+Two levers from the orchestrator side:
+
+1. **Tell the worker to read this skill in the task description**:
+   "Read the `large-input-large-output` skill before starting;
+   apply pattern 1 (read-then-summarise) and pattern 2 (skeleton
+   then fill)." Workers won't reach for that skill unless the
+   description prompts them — the skill is `scope: worker` so
+   they see it in `<available_skills>`, but they have to choose
+   to read it.
+2. **Or split the task**: one task per source file producing a
+   summary, plus one final assembly task reading only the
+   summaries. This is the bigger hammer; use it when the input
+   set is large enough (≥ 4 files, or any individual file > 30
+   KB) that even pattern 1 would push the worker close to its
+   context window.
+
+This isn't about being defensive — it's about matching the
+task shape to the underlying token economics.
+
+## Worked example: "Build me a URL shortener"
+
+User says: *Build me a URL shortener service prototype.* You,
+main agent, hear "design + build + test, single output dir,
+classic 3-role flow":
+
+**Step 1.** Read this skill (already done — you're here).
+
+**Step 2.** Read worker-creator skill (the *how* of writing
+agent.json + SOUL.md).
+
+**Step 3.** Check what already exists — reuse over create:
+```
+tenant_config_list({ path: "workers" })
+```
+For each role, walk the reuse-over-create checklist above. The
+fleet you want: `architect`, `coder`, `qa`. Suppose the tenant
+has `coder` / `llm-default` / `echo-demo`:
+
+- **architect** — no existing worker is a good fit (we want
+  one that explicitly *doesn't* code), build it.
+- **coder** — already there. Reuse, don't fork into
+  `coder-typescript` or similar.
+- **qa** — no existing fit (we want one that doesn't read
+  source), build it.
+
+Net: 2 new workers, 1 reused. Tell the user before writing:
+"I'll reuse the existing `coder` worker for the build step,
+and create `architect` + `qa` for design and testing. OK?"
+This gives them a chance to override (e.g. "please make a
+dedicated `coder-ts` for this project") before you commit.
+
+**Step 4.** Create architect:
+```
+tenant_config_write({ path: "workers/architect/agent.json", ... })
+tenant_config_write({ path: "workers/architect/SOUL.md", ... })
+```
+SOUL says: designs the API spec, writes no code, output is
+`./projects/url-shortener/spec.md`, listing endpoints + data
+model + error contract.
+
+**Step 5.** Create qa:
+```
+tenant_config_write({ path: "workers/qa/agent.json", ... })
+tenant_config_write({ path: "workers/qa/SOUL.md", ... })
+```
+SOUL says: black-box tests via curl/bash, doesn't read source
+files, produces qa-report.md with PASS/FAIL per test.
+
+**Step 6.** Drop tasks (capture each id from the response):
+```
+T1 = task_create(worker_agent_id="architect", title="Design
+  URL shortener API spec", description="<describes inputs +
+  required spec.md sections + 'don't write code' boundary>")
+
+T2 = task_create(worker_agent_id="coder", depends_on=[T1.id],
+  title="Implement URL shortener per spec", description="<read
+  spec.md, output server.js + server.test.js + package.json +
+  README.md, must npm test pass before task_complete>")
+
+T3 = task_create(worker_agent_id="qa", depends_on=[T2.id],
+  title="Black-box test the URL shortener", description="<read
+  README, start server, curl-test 6+ scenarios, qa-report.md
+  with PASS/FAIL each, summary at end>")
+```
+
+**Step 7.** Tell the user the three task ids and that the board
+will animate them in dependency order. Pool picks them up
+automatically; you don't poll.
+
+**Step 8.** When the user comes back:
+```
+task_list()
+```
+Surface the deliverables (workboard expanded cards already
+render delivery-file chips clicking through to the file open
+dialog — point the user there rather than dumping content
+inline).
+
+## Failure handling (the intervention loop)
+
+The worker pool no longer auto-retries. Every worker failure or
+watchdog timeout parks the row with the `awaiting-intervention`
+label and drops a `task_intervention_required` notification into
+your inbox. **You** decide what happens next; the pool just
+waits.
+
+The four levers (use whichever fits, never just `task_move`
+back to ready manually):
+
+- `task_continue(task_id, hint?)` — resume the SAME worker
+  session. The transcript stays; only your hint is appended.
+  Use when the prior session was on the right track and just
+  needs a small correction ("don't dump the whole HTML in one
+  write_file; use skeleton-then-fill").
+- `task_retry_fresh(task_id, description?)` — throw away the
+  prior session, start a brand new one, optionally rewrite the
+  brief. Use when the original prompt itself was the problem
+  or the worker went so far off-track that resuming is worse
+  than restarting.
+- `task_extend_timeout(task_id, additional_ms)` — the worker
+  is still doing useful work, it just needs more clock. If the
+  failure was specifically a watchdog timeout, this also
+  revives the row (no need to chain task_continue).
+- `task_abort(task_id, reason)` — give up; mark the task done
+  with a failure summary so dependents stop waiting. Use when
+  the spec is fundamentally broken or the data is missing.
+
+Diagnosis flow:
+
+1. Read the inbox `meta.interventionReason` first — watchdog
+   timeouts say so explicitly, runtime errors carry the
+   exception text, stream tears say `terminated`.
+2. If meta isn't enough, call `task_get_history(task_id)` to
+   see what the worker actually did. The last few entries are
+   usually the smoking gun (e.g. an aborted write_file with a
+   giant `content` argument means context / output blew up).
+3. Pick the lever. Output: one tool call, no extended prose
+   — the user is watching.
+
+Cascade rules: a downstream task that fails because its
+upstream delivered the wrong thing is not the worker's fault.
+Revise the upstream task (task_retry_fresh with a tighter
+description) before touching the downstream.
+
+When in doubt, ask the user — fleet design is a judgement call,
+and the user has context the description doesn't carry.
+
+## See also
+
+- `worker-creator` — the file format for agent.json / SOUL.md
+  / per-worker skills.
+- `workboard-howto` — board mechanics, task tools, delivery
+  files.
+- `skill-creator` — if you want to ship a worker its own skill
+  bundle as part of the fleet.

package/packages/server/dist/catalog.d.ts

@@ -0,0 +1,52 @@
+export interface CatalogEntry {
+    id: string;
+    displayName: string;
+    description: string;
+    author: string;
+    verified: boolean;
+    repository: string;
+    homepage?: string;
+    license?: string;
+    tags: string[];
+    latestVersion: string;
+    tarballUrl: string;
+    tarballSha256: string;
+    tarballSize?: number;
+    tianshuRange: string;
+}
+export interface CatalogSnapshot {
+    /** Source URL the snapshot was loaded from. */
+    source: string;
+    /** ISO timestamp when the host fetched the catalog (server clock). */
+    fetchedAt: string;
+    /** ISO timestamp the catalog itself reports it was last updated. */
+    catalogUpdatedAt: string | null;
+    /** Validated, ready-to-use entries. */
+    entries: CatalogEntry[];
+    /** Count of entries dropped because they failed schema checks. */
+    entriesDropped: number;
+}
+export interface CatalogClientOpts {
+    url?: string;
+    ttlMs?: number;
+    fetcher?: typeof fetch;
+}
+export declare class CatalogClient {
+    private readonly url;
+    private readonly ttlMs;
+    private readonly fetcher;
+    private cache;
+    private inflight;
+    constructor(opts?: CatalogClientOpts);
+    /**
+     * Returns the cached snapshot if still fresh; otherwise re-fetches.
+     * Concurrent calls share the same in-flight promise.
+     */
+    get(opts?: {
+        force?: boolean;
+    }): Promise<CatalogSnapshot>;
+    /** Discard the in-memory snapshot, forcing the next get() to re-fetch. */
+    invalidate(): void;
+    private fetchAndCache;
+}
+//# sourceMappingURL=catalog.d.ts.map

package/packages/server/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,uCAAuC;IACvC,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,KAAK,CAAiE;IAC9E,OAAO,CAAC,QAAQ,CAAyC;gBAE7C,IAAI,GAAE,iBAAsB;IAMxC;;;OAGG;IACG,GAAG,CAAC,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,eAAe,CAAC;IAYnE,0EAA0E;IAC1E,UAAU,IAAI,IAAI;YAIJ,aAAa;CAqC5B"}

package/packages/server/dist/catalog.js

@@ -0,0 +1,189 @@
+// Plugin Catalog client.
+//
+// Fetches the JSON catalog from a remote URL (default
+// `tianshu-ai/plugin-registry`'s `main` branch) and validates the
+// shape against the schema agreed in that repo's `schema.json`.
+//
+// v1 is intentionally minimal:
+//   - GET only, no install yet (P2 will add /install)
+//   - in-memory cache, refresh on TTL or explicit POST refresh
+//   - 1 MB hard cap on the catalog body
+//
+// We do NOT trust the remote: every required field is type-checked
+// before being handed to the API surface. Anything malformed is
+// dropped from the response with an `entriesDropped` count surfaced
+// to the client so the Plugin Manager UI can warn the user.
+const DEFAULT_CATALOG_URL = "https://raw.githubusercontent.com/tianshu-ai/plugin-registry/main/catalog.json";
+const MAX_BODY_BYTES = 1_048_576; // 1 MB
+const FETCH_TIMEOUT_MS = 10_000;
+const TTL_MS = 5 * 60 * 1000; // 5 minutes
+const ID_RE = /^[a-z0-9][a-z0-9-]{1,30}$/;
+const SHA256_RE = /^[a-f0-9]{64}$/;
+export class CatalogClient {
+    url;
+    ttlMs;
+    fetcher;
+    cache = null;
+    inflight = null;
+    constructor(opts = {}) {
+        this.url = opts.url ?? process.env.TIANSHU_CATALOG_URL ?? DEFAULT_CATALOG_URL;
+        this.ttlMs = opts.ttlMs ?? TTL_MS;
+        this.fetcher = opts.fetcher ?? fetch;
+    }
+    /**
+     * Returns the cached snapshot if still fresh; otherwise re-fetches.
+     * Concurrent calls share the same in-flight promise.
+     */
+    async get(opts = {}) {
+        const now = Date.now();
+        if (!opts.force && this.cache && this.cache.expiresAt > now) {
+            return this.cache.snapshot;
+        }
+        if (this.inflight)
+            return this.inflight;
+        this.inflight = this.fetchAndCache().finally(() => {
+            this.inflight = null;
+        });
+        return this.inflight;
+    }
+    /** Discard the in-memory snapshot, forcing the next get() to re-fetch. */
+    invalidate() {
+        this.cache = null;
+    }
+    async fetchAndCache() {
+        const fetchedAt = new Date().toISOString();
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), FETCH_TIMEOUT_MS);
+        let body;
+        try {
+            const r = await this.fetcher(this.url, {
+                signal: ac.signal,
+                headers: { accept: "application/json" },
+            });
+            if (!r.ok) {
+                throw new Error(`catalog fetch ${this.url} → ${r.status}`);
+            }
+            const cl = Number.parseInt(r.headers.get("content-length") ?? "0", 10);
+            if (Number.isFinite(cl) && cl > MAX_BODY_BYTES) {
+                throw new Error(`catalog body too large: declared ${cl} bytes`);
+            }
+            body = await r.text();
+            if (body.length > MAX_BODY_BYTES) {
+                throw new Error(`catalog body too large: ${body.length} bytes`);
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch (err) {
+            throw new Error(`catalog body is not valid JSON: ${describe(err)}`);
+        }
+        const snapshot = validateCatalog(parsed, this.url, fetchedAt);
+        this.cache = { snapshot, expiresAt: Date.now() + this.ttlMs };
+        return snapshot;
+    }
+}
+function validateCatalog(raw, source, fetchedAt) {
+    if (!isObject(raw)) {
+        throw new Error("catalog root is not an object");
+    }
+    if (raw.schemaVersion !== 1) {
+        throw new Error(`unsupported catalog schemaVersion: ${String(raw.schemaVersion)}`);
+    }
+    if (!Array.isArray(raw.plugins)) {
+        throw new Error("catalog.plugins is not an array");
+    }
+    const seenIds = new Set();
+    const entries = [];
+    let dropped = 0;
+    for (const item of raw.plugins) {
+        const e = normaliseEntry(item);
+        if (!e) {
+            dropped++;
+            continue;
+        }
+        if (seenIds.has(e.id)) {
+            dropped++;
+            continue;
+        }
+        seenIds.add(e.id);
+        entries.push(e);
+    }
+    return {
+        source,
+        fetchedAt,
+        catalogUpdatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : null,
+        entries,
+        entriesDropped: dropped,
+    };
+}
+function normaliseEntry(raw) {
+    if (!isObject(raw))
+        return null;
+    const { id, displayName, description, author, verified, repository, homepage, license, tags, latestVersion, tarballUrl, tarballSha256, tarballSize, tianshuRange, } = raw;
+    if (typeof id !== "string" || !ID_RE.test(id))
+        return null;
+    if (!nonEmptyString(displayName) || displayName.length > 80)
+        return null;
+    if (!nonEmptyString(description) || description.length > 500)
+        return null;
+    if (!nonEmptyString(author))
+        return null;
+    if (!isHttpUrl(repository))
+        return null;
+    if (!nonEmptyString(latestVersion))
+        return null;
+    if (!isHttpUrl(tarballUrl))
+        return null;
+    if (typeof tarballSha256 !== "string" || !SHA256_RE.test(tarballSha256))
+        return null;
+    if (!nonEmptyString(tianshuRange))
+        return null;
+    const cleanedTags = [];
+    if (Array.isArray(tags)) {
+        for (const t of tags) {
+            if (typeof t === "string" && t.length > 0 && t.length <= 32 && cleanedTags.length < 10) {
+                cleanedTags.push(t);
+            }
+        }
+    }
+    return {
+        id,
+        displayName,
+        description,
+        author,
+        verified: verified === true,
+        repository,
+        homepage: typeof homepage === "string" && isHttpUrl(homepage) ? homepage : undefined,
+        license: nonEmptyString(license) ? license : undefined,
+        tags: cleanedTags,
+        latestVersion,
+        tarballUrl,
+        tarballSha256,
+        tarballSize: typeof tarballSize === "number" && Number.isInteger(tarballSize) && tarballSize > 0
+            ? tarballSize
+            : undefined,
+        tianshuRange,
+    };
+}
+function isObject(x) {
+    return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+function nonEmptyString(x) {
+    return typeof x === "string" && x.length > 0;
+}
+function isHttpUrl(x) {
+    if (typeof x !== "string")
+        return false;
+    return x.startsWith("https://") || x.startsWith("http://");
+}
+function describe(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+//# sourceMappingURL=catalog.js.map

package/packages/server/dist/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"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"}