npm - @ulysses-ai/create-workspace - Versions diffs - 0.14.0-beta.3 → 0.15.0-beta.0 - Mend

@ulysses-ai/create-workspace 0.14.0-beta.3 → 0.15.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (41) hide show

package/template/.claude/scripts/capture-context.mjs ADDED Viewed

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// Centralized capture helper for /braindump, /handoff, /aside, /promote.
+// Mechanizes the path math, naming convention, and frontmatter so skills
+// don't have to duplicate it (and can't drift from each other).
+//
+// Usage:
+//   echo "<body>" | node capture-context.mjs \
+//     --type braindump|handoff|research \
+//     --topic kebab-case-slug \
+//     --scope shared|team-member \
+//     [--user alice]            # required when --scope team-member
+//     [--description "..."]     # one-line summary, used by index
+//     [--variant aside]         # arbitrary frontmatter marker
+//     [--local-only]            # prefix filename with local-only- (gitignored)
+//     [--update]                # overwrite if file exists; default appends -2, -3, ...
+//     [--root <path>]           # workspace root (defaults to cwd)
+//     [--print-only]            # don't write; just print the planned path
+//
+// Path layout:
+//   shared scope:      workspace-context/shared/{type}_{topic}.md
+//   team-member scope: workspace-context/team-member/{user}/{type}_{topic}.md
+// With --local-only, the file basename is prefixed `local-only-` (e.g.
+// `local-only-research_my-topic.md`), so the gitignore pattern keeps it
+// out of git.
+//
+// Stdin: the markdown body to write under the frontmatter. Required unless
+// --print-only is passed.
+//
+// Stdout: a single line with the absolute path of the written (or planned) file.
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+function isMainModule(metaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(metaUrl)) === realpathSync(process.argv[1]);
+  } catch { return false; }
+}
+const VALID_TYPES = new Set(['braindump', 'handoff', 'research']);
+const VALID_SCOPES = new Set(['shared', 'team-member']);
+const WC_DIR = 'workspace-context';
+const SHARED_DIR = 'shared';
+const TEAM_MEMBER_DIR = 'team-member';
+function parseArgs(argv) {
+  const args = {
+    type: null,
+    topic: null,
+    scope: null,
+    user: null,
+    description: null,
+    variant: null,
+    localOnly: false,
+    update: false,
+    root: process.cwd(),
+    printOnly: false,
+  };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--type') args.type = argv[++i];
+    else if (a === '--topic') args.topic = argv[++i];
+    else if (a === '--scope') args.scope = argv[++i];
+    else if (a === '--user') args.user = argv[++i];
+    else if (a === '--description') args.description = argv[++i];
+    else if (a === '--variant') args.variant = argv[++i];
+    else if (a === '--local-only') args.localOnly = true;
+    else if (a === '--update') args.update = true;
+    else if (a === '--root') args.root = argv[++i];
+    else if (a === '--print-only') args.printOnly = true;
+    else throw new Error(`Unknown arg: ${a}`);
+  }
+  return args;
+}
+function validate(args) {
+  if (!args.type || !VALID_TYPES.has(args.type)) {
+    throw new Error(`--type must be one of: ${[...VALID_TYPES].join(', ')}`);
+  }
+  if (!args.topic || !/^[a-z0-9][a-z0-9-]*$/.test(args.topic)) {
+    throw new Error('--topic must be kebab-case (lowercase letters, digits, hyphens)');
+  }
+  if (!args.scope || !VALID_SCOPES.has(args.scope)) {
+    throw new Error(`--scope must be one of: ${[...VALID_SCOPES].join(', ')}`);
+  }
+  if (args.scope === 'team-member' && !args.user) {
+    throw new Error('--user is required when --scope is team-member');
+  }
+  if (args.scope === 'team-member' && !/^[A-Za-z0-9_-]+$/.test(args.user)) {
+    throw new Error('--user must be alphanumeric (with optional - or _)');
+  }
+}
+function computeDir(args) {
+  if (args.scope === 'shared') {
+    return join(args.root, WC_DIR, SHARED_DIR);
+  }
+  return join(args.root, WC_DIR, TEAM_MEMBER_DIR, args.user);
+}
+function computeBaseFilename(args) {
+  const prefix = args.localOnly ? 'local-only-' : '';
+  return `${prefix}${args.type}_${args.topic}.md`;
+}
+function resolveCollision(dir, baseFilename, update) {
+  const initial = join(dir, baseFilename);
+  if (update) return initial;
+  if (!existsSync(initial)) return initial;
+  const dot = baseFilename.lastIndexOf('.');
+  const stem = baseFilename.slice(0, dot);
+  const ext = baseFilename.slice(dot);
+  for (let i = 2; i < 1000; i++) {
+    const candidate = join(dir, `${stem}-${i}${ext}`);
+    if (!existsSync(candidate)) return candidate;
+  }
+  throw new Error(`Could not find unique filename for ${baseFilename} (1000+ collisions)`);
+}
+function todayISO() {
+  return new Date().toISOString().slice(0, 10);
+}
+function buildFrontmatter(args) {
+  const fm = {
+    state: 'ephemeral',
+    lifecycle: 'active',
+    type: args.type,
+    topic: args.topic,
+  };
+  if (args.scope === 'team-member') fm.author = args.user;
+  if (args.variant) fm.variant = args.variant;
+  if (args.description) fm.description = args.description;
+  fm.updated = todayISO();
+  return fm;
+}
+function renderFrontmatter(fm) {
+  const lines = ['---'];
+  for (const [k, v] of Object.entries(fm)) {
+    lines.push(`${k}: ${v}`);
+  }
+  lines.push('---');
+  return lines.join('\n');
+}
+function readStdinSync() {
+  try {
+    return readFileSync(0, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+function plan(args) {
+  validate(args);
+  const dir = computeDir(args);
+  const baseFilename = computeBaseFilename(args);
+  const filePath = resolveCollision(dir, baseFilename, args.update);
+  return { dir, filePath, frontmatter: buildFrontmatter(args) };
+}
+function write(args, body) {
+  const planned = plan(args);
+  ensureDir(planned.dir);
+  const content = renderFrontmatter(planned.frontmatter) + '\n\n' + body.replace(/^\n+/, '');
+  const finalContent = content.endsWith('\n') ? content : content + '\n';
+  writeFileSync(planned.filePath, finalContent);
+  return planned.filePath;
+}
+function main() {
+  const args = parseArgs(process.argv);
+  args.root = resolve(args.root);
+  if (args.printOnly) {
+    const planned = plan(args);
+    process.stdout.write(planned.filePath + '\n');
+    return;
+  }
+  const body = readStdinSync();
+  if (!body || !body.trim()) {
+    throw new Error('No body content on stdin (use --print-only to skip writing)');
+  }
+  const filePath = write(args, body);
+  process.stdout.write(filePath + '\n');
+}
+if (isMainModule(import.meta.url)) {
+  try {
+    main();
+  } catch (err) {
+    process.stderr.write(`capture-context: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+export {
+  parseArgs,
+  validate,
+  computeDir,
+  computeBaseFilename,
+  resolveCollision,
+  buildFrontmatter,
+  renderFrontmatter,
+  plan,
+  write,
+};

package/template/.claude/scripts/capture-context.test.mjs ADDED Viewed

@@ -0,0 +1,383 @@
+#!/usr/bin/env node
+// Unit tests for capture-context.mjs
+// Run: node template/.claude/scripts/capture-context.test.mjs
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import {
+  parseArgs,
+  validate,
+  computeDir,
+  computeBaseFilename,
+  resolveCollision,
+  buildFrontmatter,
+  renderFrontmatter,
+  plan,
+  write,
+} from './capture-context.mjs';
+let failed = 0;
+let passed = 0;
+function assert(cond, msg) {
+  if (cond) { passed++; } else { failed++; console.error(`  FAIL: ${msg}`); }
+}
+function assertEq(actual, expected, msg) {
+  const a = JSON.stringify(actual);
+  const e = JSON.stringify(expected);
+  if (a === e) { passed++; } else {
+    failed++;
+    console.error(`  FAIL: ${msg}\n    expected: ${e}\n    actual:   ${a}`);
+  }
+}
+function assertThrows(fn, matcher, msg) {
+  try {
+    fn();
+    failed++;
+    console.error(`  FAIL: ${msg} (expected throw)`);
+  } catch (e) {
+    if (matcher.test(e.message)) { passed++; }
+    else { failed++; console.error(`  FAIL: ${msg}\n    error: ${e.message}`); }
+  }
+}
+function setupRoot() {
+  return mkdtempSync(join(tmpdir(), 'cap-test-'));
+}
+function cleanup(root) {
+  rmSync(root, { recursive: true, force: true });
+}
+console.log('# validate');
+{
+  assertThrows(
+    () => validate({ type: null, topic: 'x', scope: 'shared' }),
+    /--type must be one of/,
+    'rejects missing type',
+  );
+}
+{
+  assertThrows(
+    () => validate({ type: 'memo', topic: 'x', scope: 'shared' }),
+    /--type must be one of/,
+    'rejects invalid type',
+  );
+}
+{
+  assertThrows(
+    () => validate({ type: 'braindump', topic: 'BadCase', scope: 'shared' }),
+    /kebab-case/,
+    'rejects non-kebab-case topic',
+  );
+}
+{
+  assertThrows(
+    () => validate({ type: 'braindump', topic: 'x', scope: 'invalid' }),
+    /--scope must be one of/,
+    'rejects invalid scope',
+  );
+}
+{
+  assertThrows(
+    () => validate({ type: 'braindump', topic: 'x', scope: 'team-member' }),
+    /--user is required/,
+    'rejects team-member scope without user',
+  );
+}
+{
+  assertThrows(
+    () => validate({ type: 'braindump', topic: 'x', scope: 'team-member', user: 'bad/name' }),
+    /--user must be alphanumeric/,
+    'rejects user with slash',
+  );
+}
+{
+  // valid input doesn't throw
+  validate({ type: 'braindump', topic: 'my-topic', scope: 'shared' });
+  validate({ type: 'handoff', topic: 'my-topic', scope: 'team-member', user: 'alice' });
+  passed += 2;
+}
+console.log('# computeDir');
+{
+  const sharedDir = computeDir({ scope: 'shared', root: '/ws' });
+  assertEq(sharedDir, '/ws/workspace-context/shared', 'shared scope path');
+  const userDir = computeDir({ scope: 'team-member', user: 'alice', root: '/ws' });
+  assertEq(userDir, '/ws/workspace-context/team-member/alice', 'team-member scope path');
+}
+console.log('# computeBaseFilename');
+{
+  assertEq(
+    computeBaseFilename({ type: 'braindump', topic: 'my-thing', localOnly: false }),
+    'braindump_my-thing.md',
+    'standard naming',
+  );
+  assertEq(
+    computeBaseFilename({ type: 'research', topic: 'my-thing', localOnly: true }),
+    'local-only-research_my-thing.md',
+    'local-only prefix applied',
+  );
+  assertEq(
+    computeBaseFilename({ type: 'handoff', topic: 'workstream-x', localOnly: false }),
+    'handoff_workstream-x.md',
+    'handoff prefix',
+  );
+}
+console.log('# resolveCollision');
+{
+  const root = setupRoot();
+  const path1 = resolveCollision(root, 'braindump_x.md', false);
+  assertEq(path1, join(root, 'braindump_x.md'), 'no collision returns base');
+  cleanup(root);
+}
+{
+  const root = setupRoot();
+  writeFileSync(join(root, 'braindump_x.md'), 'first');
+  const path2 = resolveCollision(root, 'braindump_x.md', false);
+  assertEq(path2, join(root, 'braindump_x-2.md'), 'first collision → -2');
+  writeFileSync(path2, 'second');
+  const path3 = resolveCollision(root, 'braindump_x.md', false);
+  assertEq(path3, join(root, 'braindump_x-3.md'), 'second collision → -3');
+  cleanup(root);
+}
+{
+  const root = setupRoot();
+  writeFileSync(join(root, 'braindump_x.md'), 'first');
+  const path = resolveCollision(root, 'braindump_x.md', true);
+  assertEq(path, join(root, 'braindump_x.md'), '--update returns base even when exists');
+  cleanup(root);
+}
+console.log('# buildFrontmatter');
+{
+  const fm = buildFrontmatter({
+    type: 'braindump',
+    topic: 'my-thing',
+    scope: 'shared',
+  });
+  assertEq(fm.state, 'ephemeral', 'state ephemeral');
+  assertEq(fm.lifecycle, 'active', 'lifecycle active');
+  assertEq(fm.type, 'braindump', 'type set');
+  assertEq(fm.topic, 'my-thing', 'topic set');
+  assert(!('author' in fm), 'no author for shared scope');
+  assert(/^\d{4}-\d{2}-\d{2}$/.test(fm.updated), 'updated is ISO date');
+}
+{
+  const fm = buildFrontmatter({
+    type: 'research',
+    topic: 'idea',
+    scope: 'team-member',
+    user: 'alice',
+    variant: 'aside',
+    description: 'A neat idea.',
+  });
+  assertEq(fm.author, 'alice', 'author from --user');
+  assertEq(fm.variant, 'aside', 'variant included');
+  assertEq(fm.description, 'A neat idea.', 'description included');
+}
+console.log('# renderFrontmatter');
+{
+  const out = renderFrontmatter({
+    state: 'ephemeral',
+    type: 'braindump',
+    topic: 'x',
+  });
+  assertEq(
+    out,
+    '---\nstate: ephemeral\ntype: braindump\ntopic: x\n---',
+    'frontmatter rendered with --- fences',
+  );
+}
+console.log('# plan');
+{
+  const root = setupRoot();
+  const planned = plan({
+    type: 'braindump',
+    topic: 'my-topic',
+    scope: 'team-member',
+    user: 'alice',
+    root,
+    localOnly: false,
+    update: false,
+  });
+  assertEq(
+    planned.filePath,
+    join(root, 'workspace-context', 'team-member', 'alice', 'braindump_my-topic.md'),
+    'planned path includes type prefix and user dir',
+  );
+  cleanup(root);
+}
+{
+  const root = setupRoot();
+  const args = {
+    type: 'research',
+    topic: 'idea',
+    scope: 'team-member',
+    user: 'alice',
+    root,
+    localOnly: true,
+    update: false,
+    variant: 'aside',
+  };
+  const planned = plan(args);
+  assertEq(
+    planned.filePath,
+    join(root, 'workspace-context', 'team-member', 'alice', 'local-only-research_idea.md'),
+    'local-only flag prefixes filename',
+  );
+  cleanup(root);
+}
+console.log('# write end-to-end');
+{
+  const root = setupRoot();
+  const filePath = write(
+    {
+      type: 'braindump',
+      topic: 'my-topic',
+      scope: 'team-member',
+      user: 'alice',
+      description: 'Captured my topic.',
+      root,
+      localOnly: false,
+      update: false,
+    },
+    '## Section\n\nBody text.\n',
+  );
+  assert(existsSync(filePath), 'file written');
+  const content = readFileSync(filePath, 'utf-8');
+  assert(content.startsWith('---\n'), 'starts with frontmatter');
+  assert(content.includes('type: braindump'), 'frontmatter has type');
+  assert(content.includes('topic: my-topic'), 'frontmatter has topic');
+  assert(content.includes('author: alice'), 'frontmatter has author');
+  assert(content.includes('description: Captured my topic.'), 'frontmatter has description');
+  assert(content.includes('## Section\n\nBody text.'), 'body preserved');
+  cleanup(root);
+}
+{
+  // collision: second write becomes -2
+  const root = setupRoot();
+  const args = {
+    type: 'braindump',
+    topic: 'topic',
+    scope: 'shared',
+    root,
+    localOnly: false,
+    update: false,
+  };
+  const path1 = write(args, 'first body');
+  const path2 = write(args, 'second body');
+  assert(path1 !== path2, 'collision creates new path');
+  assert(path2.endsWith('braindump_topic-2.md'), 'second is -2');
+  cleanup(root);
+}
+{
+  // --update: overwrites existing
+  const root = setupRoot();
+  const args = {
+    type: 'braindump',
+    topic: 'topic',
+    scope: 'shared',
+    root,
+    localOnly: false,
+    update: false,
+  };
+  const path1 = write(args, 'first body');
+  const path2 = write({ ...args, update: true }, 'updated body');
+  assertEq(path1, path2, '--update overwrites same path');
+  const content = readFileSync(path1, 'utf-8');
+  assert(content.includes('updated body'), 'content overwritten');
+  assert(!content.includes('first body'), 'old content gone');
+  cleanup(root);
+}
+console.log('# CLI end-to-end');
+{
+  const root = setupRoot();
+  const scriptPath = new URL('./capture-context.mjs', import.meta.url).pathname;
+  const result = spawnSync(
+    'node',
+    [scriptPath, '--type', 'braindump', '--topic', 'cli-test', '--scope', 'shared', '--root', root],
+    { input: '## Body\n\nFrom stdin.\n', encoding: 'utf-8' },
+  );
+  assertEq(result.status, 0, 'CLI exits 0');
+  const printedPath = result.stdout.trim();
+  assert(printedPath.endsWith('braindump_cli-test.md'), 'CLI prints path with prefix');
+  const content = readFileSync(printedPath, 'utf-8');
+  assert(content.includes('From stdin.'), 'stdin body written');
+  cleanup(root);
+}
+{
+  // --print-only: no stdin needed, no file written
+  const root = setupRoot();
+  const scriptPath = new URL('./capture-context.mjs', import.meta.url).pathname;
+  const result = spawnSync(
+    'node',
+    [
+      scriptPath,
+      '--type', 'handoff',
+      '--topic', 'no-write',
+      '--scope', 'team-member',
+      '--user', 'bob',
+      '--root', root,
+      '--print-only',
+    ],
+    { encoding: 'utf-8' },
+  );
+  assertEq(result.status, 0, '--print-only exits 0');
+  const printedPath = result.stdout.trim();
+  assert(printedPath.endsWith('handoff_no-write.md'), 'planned path printed');
+  assert(!existsSync(printedPath), 'no file written in print-only mode');
+  cleanup(root);
+}
+{
+  // bad arg
+  const root = setupRoot();
+  const scriptPath = new URL('./capture-context.mjs', import.meta.url).pathname;
+  const result = spawnSync(
+    'node',
+    [scriptPath, '--type', 'invalid', '--topic', 'x', '--scope', 'shared', '--root', root],
+    { input: 'body', encoding: 'utf-8' },
+  );
+  assertEq(result.status, 1, 'invalid type exits 1');
+  assert(result.stderr.includes('--type must be one of'), 'error message piped to stderr');
+  cleanup(root);
+}
+console.log('');
+console.log(`${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/template/.claude/scripts/generate-claude-local.mjs ADDED Viewed

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// Write CLAUDE.local.md at the workspace root with the per-user import.
+//
+// CLAUDE.local.md is gitignored — it carries user-scoped context that
+// shouldn't propagate across team members. The single source of identity
+// is `.claude/settings.local.json` → `workspace.user`.
+//
+// Usage:
+//   node generate-claude-local.mjs [--root <path>] [--force]
+//
+// Behavior:
+//   - Reads workspace.user from .claude/settings.local.json
+//   - Refuses to overwrite an existing CLAUDE.local.md unless --force
+//   - Idempotent: same input → same content
+//
+// Exit codes:
+//   0 — wrote (or would have written) the file
+//   1 — error (missing settings, settings missing user, refusal to overwrite)
+import { readFileSync, writeFileSync, existsSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+function isMainModule(metaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(metaUrl)) === realpathSync(process.argv[1]);
+  } catch { return false; }
+}
+function parseArgs(argv) {
+  const args = { root: process.cwd(), force: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--root') args.root = argv[++i];
+    else if (a === '--force') args.force = true;
+    else throw new Error(`Unknown arg: ${a}`);
+  }
+  return args;
+}
+function readWorkspaceUser(root) {
+  const settingsPath = join(root, '.claude', 'settings.local.json');
+  if (!existsSync(settingsPath)) {
+    throw new Error(`Missing ${settingsPath} — run /workspace-init first`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+  } catch (e) {
+    throw new Error(`Could not parse ${settingsPath}: ${e.message}`);
+  }
+  const user = parsed?.workspace?.user;
+  if (!user || typeof user !== 'string') {
+    throw new Error(`workspace.user not set in ${settingsPath}`);
+  }
+  if (!/^[A-Za-z0-9_-]+$/.test(user)) {
+    throw new Error(`workspace.user "${user}" must be alphanumeric (with optional - or _)`);
+  }
+  return user;
+}
+function renderClaudeLocal(user) {
+  return `## My Context
+@workspace-context/team-member/${user}/index.md
+`;
+}
+function generateClaudeLocal(root, { force = false } = {}) {
+  const user = readWorkspaceUser(root);
+  const target = join(root, 'CLAUDE.local.md');
+  const content = renderClaudeLocal(user);
+  if (existsSync(target) && !force) {
+    const existing = readFileSync(target, 'utf-8');
+    if (existing === content) {
+      return { path: target, status: 'unchanged' };
+    }
+    throw new Error(
+      `${target} already exists with different content. Re-run with --force to overwrite.`,
+    );
+  }
+  writeFileSync(target, content);
+  return { path: target, status: existsSync(target) ? 'written' : 'written' };
+}
+function main() {
+  const args = parseArgs(process.argv);
+  const root = resolve(args.root);
+  const result = generateClaudeLocal(root, { force: args.force });
+  process.stdout.write(JSON.stringify(result) + '\n');
+}
+if (isMainModule(import.meta.url)) {
+  try {
+    main();
+  } catch (err) {
+    process.stderr.write(`generate-claude-local: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+export { readWorkspaceUser, renderClaudeLocal, generateClaudeLocal };