@rsconcept/rstool 1.9.0 → 2.0.0

package/skills/scripts/check-brief.ts

@@ -0,0 +1,94 @@
+/**
+ * CLI: check a session against its brief and print readiness.
+ *
+ * Usage (from the rstool package root):
+ *   tsx skills/scripts/check-brief.ts --session <session.json> --brief <brief.json> [--base <v1-session.json>] [--review] [--json]
+ *
+ * Exit code: 0 — no blockers, 1 — blockers, 2 — usage or input error.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { type Brief, checkBrief, type BriefCheckResult } from './brief-check';
+
+function parseArgs(argv: string[]): Record<string, string | true> {
+  const args: Record<string, string | true> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const key = argv[i];
+    if (!key.startsWith('--')) {
+      continue;
+    }
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('--')) {
+      args[key.slice(2)] = true;
+    } else {
+      args[key.slice(2)] = next;
+      i++;
+    }
+  }
+  return args;
+}
+
+function readText(path: string): string {
+  return readFileSync(resolve(path), 'utf8').replace(/^/, '');
+}
+
+function printReport({ readiness, scenarios }: BriefCheckResult) {
+  const lines: string[] = [];
+  lines.push(`Этап: ${readiness.stage}${readiness.ready ? ' — блокеров нет' : ''}`);
+  lines.push(`Диагностики: ошибок ${readiness.diagnostics.errors}, предупреждений ${readiness.diagnostics.warnings}`);
+  lines.push(
+    `Покрытие: требования ${readiness.coverage.expressiveness}, инварианты ${readiness.coverage.invariants}, различения ${readiness.coverage.distinctions}`
+  );
+  lines.push(
+    `Сценарии: прошло ${readiness.scenarios.passed}, провалено ${readiness.scenarios.failed}, не хватает ${readiness.scenarios.missing}`
+  );
+  if (scenarios.length > 0) {
+    lines.push('', 'Матрица приёмки:');
+    for (const scenario of scenarios) {
+      lines.push(
+        `  ${scenario.passed ? '✓' : '✗'} ${scenario.id} ${scenario.title}${scenario.error ? ` — ${scenario.error}` : ''}`
+      );
+      for (const check of scenario.checks) {
+        lines.push(
+          `      ${check.passed ? '✓' : '✗'} ${check.target}: ожидалось ${check.expected}, получено ${check.actual}`
+        );
+      }
+    }
+  }
+  if (readiness.blockers.length > 0) {
+    lines.push('', 'Блокеры:', ...readiness.blockers.map(item => `  - ${item}`));
+  }
+  if (readiness.warnings.length > 0) {
+    lines.push('', 'Предупреждения:', ...readiness.warnings.map(item => `  - ${item}`));
+  }
+  lines.push('', `Дальше: ${readiness.next}`);
+  console.log(lines.join('\n'));
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (typeof args.session !== 'string' || typeof args.brief !== 'string') {
+    console.error(
+      'Usage: tsx skills/scripts/check-brief.ts --session <session.json> --brief <brief.json> [--base <session.json>] [--review] [--json]'
+    );
+    process.exit(2);
+  }
+  const result = await checkBrief({
+    session: readText(args.session),
+    brief: JSON.parse(readText(args.brief)) as Brief,
+    base: typeof args.base === 'string' ? readText(args.base) : undefined,
+    mode: args.review ? 'review' : 'build'
+  });
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printReport(result);
+  }
+  process.exit(result.readiness.ready ? 0 : 1);
+}
+
+main().catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(2);
+});

package/skills/scripts/rstool-skills.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * Writes the `rstool` entry skill stub into a project skills directory.
+ *
+ * The stub holds only `name`, `description` and the path to the real router skill,
+ * so nothing has to be re-synced after a package update. Which directory a host loads
+ * is the agent's call (skills/INSTALL.md), so there is no default `--dir`.
+ *
+ * Usage:
+ *   rstool-skills install --dir <skills-dir>... [--source <router SKILL.md>] [--target <path>]
+ *   rstool-skills stub [--source <router SKILL.md>] [--target <path>]   (prints the stub)
+ *
+ * Defaults: --source — router skill of this package; --target — its path from the
+ * current directory, or node_modules/@rsconcept/rstool/skills/rstool/SKILL.md when
+ * the package lies outside it.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROUTER = fileURLToPath(new URL('../rstool/SKILL.md', import.meta.url));
+
+/** Extracts the YAML front matter `description` block (folded `>-` or single line) verbatim. */
+export function readDescription(skillText) {
+  const match = /^---\n([\s\S]*?)\n---/.exec(skillText.replace(/\r\n/g, '\n'));
+  if (!match) {
+    throw new Error('SKILL.md has no front matter');
+  }
+  const lines = match[1].split('\n');
+  const start = lines.findIndex(line => line.startsWith('description:'));
+  if (start < 0) {
+    throw new Error('SKILL.md has no description');
+  }
+  const block = [lines[start]];
+  for (const line of lines.slice(start + 1)) {
+    if (!line.startsWith(' ')) {
+      break;
+    }
+    block.push(line);
+  }
+  return block.join('\n');
+}
+
+/** Renders the stub skill pointing at `targetPath` (written as is, use forward slashes). */
+export function renderStub(skillText, targetPath) {
+  return [
+    '---',
+    'name: rstool',
+    readDescription(skillText),
+    '---',
+    '',
+    '# rstool',
+    '',
+    `Заглушка для автосрабатывания. Прочитай \`${targetPath}\` и следуй ему.`,
+    '',
+    'Содержимое скилла — только там; эта заглушка его не повторяет и обновлять её после обновления пакета не нужно.',
+    ''
+  ].join('\n');
+}
+
+function parseArgs(argv) {
+  const args = { dirs: [], source: undefined, target: undefined };
+  for (let i = 0; i < argv.length; i++) {
+    const value = argv[i + 1];
+    if (argv[i] === '--dir') {
+      args.dirs.push(value);
+      i++;
+    } else if (argv[i] === '--source') {
+      args.source = value;
+      i++;
+    } else if (argv[i] === '--target') {
+      args.target = value;
+      i++;
+    }
+  }
+  return args;
+}
+
+function stubTarget(args, source) {
+  const fromProject = relative(process.cwd(), source).split('\\').join('/');
+  return (
+    args.target ??
+    (fromProject.startsWith('..') ? 'node_modules/@rsconcept/rstool/skills/rstool/SKILL.md' : fromProject)
+  );
+}
+
+function install(args) {
+  const source = resolve(args.source ?? ROUTER);
+  const text = readFileSync(source, 'utf8');
+  const target = stubTarget(args, source);
+  for (const dir of args.dirs) {
+    const path = join(dir, 'rstool', 'SKILL.md');
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, renderStub(text, target), 'utf8');
+    console.log(`wrote ${path} → ${target}`);
+    const legacy = join(dir, 'rstool-helper', 'SKILL.md');
+    if (existsSync(legacy)) {
+      console.log(`note: ${legacy} is the old copied skill; remove it — rstool replaces it`);
+    }
+  }
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const [command, ...rest] = process.argv.slice(2);
+  const args = parseArgs(rest);
+  if (command === 'install' && args.dirs.length > 0) {
+    install(args);
+  } else if (command === 'stub') {
+    const source = resolve(args.source ?? ROUTER);
+    process.stdout.write(renderStub(readFileSync(source, 'utf8'), stubTarget(args, source)));
+  } else {
+    console.error(
+      'Usage: rstool-skills install --dir <skills-dir>... | rstool-skills stub [--source <SKILL.md>] [--target <path>]\n' +
+        'Which skills directory to use: node_modules/@rsconcept/rstool/skills/INSTALL.md'
+    );
+    process.exit(2);
+  }
+}

package/skills/scripts/skill-stubs.test.ts

@@ -0,0 +1,48 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+const SCRIPT = resolve(import.meta.dirname, 'rstool-skills.mjs');
+const ROUTER = resolve(import.meta.dirname, '../rstool/SKILL.md');
+const WORKSPACE = resolve(import.meta.dirname, '../../../..');
+const STUBS = ['.agents/skills/rstool/SKILL.md', '.claude/skills/rstool/SKILL.md'];
+
+function renderStub(target: string): string {
+  return execFileSync('node', [SCRIPT, 'stub', '--source', ROUTER, '--target', target], { encoding: 'utf8' });
+}
+
+describe('rstool skill stubs', () => {
+  it.each(STUBS)('workspace %s matches the router skill', stub => {
+    const path = join(WORKSPACE, stub);
+    if (!existsSync(path)) {
+      return;
+    }
+    expect(readFileSync(path, 'utf8')).toBe(renderStub('rsconcept/rstool/skills/rstool/SKILL.md'));
+  });
+
+  it('install requires an explicit skills directory', () => {
+    const project = mkdtempSync(join(tmpdir(), 'rstool-skills-'));
+    try {
+      expect(() => execFileSync('node', [SCRIPT, 'install'], { cwd: project, stdio: 'pipe' })).toThrow();
+      expect(existsSync(join(project, '.claude'))).toBe(false);
+      expect(existsSync(join(project, '.agents'))).toBe(false);
+    } finally {
+      rmSync(project, { recursive: true, force: true });
+    }
+  });
+
+  it('installs a stub that points into node_modules', () => {
+    const project = mkdtempSync(join(tmpdir(), 'rstool-skills-'));
+    try {
+      execFileSync('node', [SCRIPT, 'install', '--dir', 'skills'], { cwd: project, encoding: 'utf8' });
+      const stub = readFileSync(join(project, 'skills/rstool/SKILL.md'), 'utf8');
+      expect(stub).toBe(renderStub('node_modules/@rsconcept/rstool/skills/rstool/SKILL.md'));
+      expect(stub).toContain('name: rstool');
+    } finally {
+      rmSync(project, { recursive: true, force: true });
+    }
+  });
+});