@dotdrelle/wiki-manager 0.6.17

package/src/core/plan.js

@@ -0,0 +1,181 @@
+export function ensurePlanFromActivity(session, activity) {
+  if (!activity) return;
+  const actKey = activity.key ?? null;
+  // Same activity still being tracked — preserve current plan state (polling update).
+  if (session.headlessPlan && actKey !== null && session.headlessPlan[0]?._activityKey === actKey) return;
+  const steps = activity.plan?.steps;
+  if (Array.isArray(steps) && steps.length > 0) {
+    session.headlessPlan = steps.map((s, i) => ({
+      step: i + 1,
+      id: s.id ?? null,
+      description: s.label,
+      status: 'pending',
+      _activityKey: activity.key,
+    }));
+  } else {
+    session.headlessPlan = [{
+      step: 1,
+      id: null,
+      description: activity.label,
+      status: 'pending',
+      _activityKey: activity.key,
+    }];
+  }
+  session._onPlanUpdate?.();
+}
+
+export function extractHeadlessPlan(text) {
+  const steps = [];
+  for (const line of text.split('\n')) {
+    const m = line.match(/^\s*(\d+)[.)]\s+(.+)/);
+    if (m) steps.push({ step: Number(m[1]), description: m[2].trim(), status: 'pending' });
+  }
+  if (steps.length < 2 || steps[0].step !== 1) return null;
+  return steps;
+}
+
+export function matchCompletedToPlan(plan, completed) {
+  if (!plan) return;
+  syncActivitiesToPlan(plan, completed.filter((activity) => activity.terminal));
+}
+
+export function syncActivitiesToPlan(plan, activities) {
+  if (!plan) return;
+  for (const activity of activities ?? []) {
+    const terminal = Boolean(activity.terminal);
+    const failed = ['failed', 'error', 'cancelled', 'canceled'].includes(String(activity.status).toLowerCase());
+    const actKey = activity.key ?? activity.id ?? activity.jobId ?? null;
+    const matched = findMatchingPlanStepByStructure(plan, activity) ?? findMatchingPlanStep(plan, activity);
+    if (!matched) continue;
+
+    if (terminal && !failed) {
+      // Structured plan: mark all steps owned by this activity as done.
+      // Legacy plan (no _activityKey): mark all steps up to matched as done (sequential assumption).
+      const ownedSteps = actKey ? plan.filter((s) => s._activityKey === actKey) : [];
+      if (ownedSteps.length > 0) {
+        for (const step of ownedSteps) {
+          if (step.status !== 'failed') {
+            step.status = 'done';
+            step.activityKey = actKey;
+          }
+        }
+      } else {
+        for (const step of plan) {
+          if (step.status === 'failed') continue;
+          if (step.step <= matched.step) {
+            step.status = 'done';
+            step.activityKey = actKey;
+          }
+        }
+      }
+    } else if (terminal && failed) {
+      matched.status = 'failed';
+      matched.activityKey = actKey;
+    } else if (!failed) {
+      // Running: matched step is in progress; preceding pending steps are implicitly done.
+      for (const step of plan) {
+        if (step.status === 'failed') continue;
+        if (step.step < matched.step && step.status === 'pending') {
+          step.status = 'done';
+          step.activityKey = actKey;
+        } else if (step.step === matched.step) {
+          step.status = 'running';
+          step.activityKey = actKey;
+        }
+      }
+    }
+  }
+}
+
+export function formatPlanStatus(plan) {
+  return plan
+    .map((s) => {
+      const icon = s.status === 'done' ? '✓' : s.status === 'failed' ? '✗' : s.status === 'running' ? '…' : ' ';
+      return `${s.step}. [${icon}] ${s.description}`;
+    })
+    .join('\n');
+}
+
+export function formatCompletedActivities(activities) {
+  return activities
+    .filter((a) => a.terminal)
+    .map((a) => `- ${a.source} ${a.id ?? a.kind}: ${a.status}${a.error ? ` (${a.error})` : ''}`)
+    .join('\n');
+}
+
+function findMatchingPlanStepByStructure(plan, activity) {
+  const actKey = activity.key ?? null;
+  const stepId = activity.progress?.stepId ?? null;
+  const stepIndex = activity.progress?.stepIndex ?? null;
+
+  function compatible(step) {
+    return !step._activityKey || !actKey || step._activityKey === actKey;
+  }
+
+  if (stepId !== null) {
+    const found = plan.find((s) => s.id != null && String(s.id) === stepId && compatible(s));
+    if (found) return found;
+  }
+  if (stepIndex !== null && Number.isFinite(Number(stepIndex))) {
+    const found = plan.find((s) => s.step === Number(stepIndex) && compatible(s));
+    if (found) return found;
+  }
+  return null;
+}
+
+function findMatchingPlanStep(plan, activity) {
+  const actKey = activity.key ?? null;
+  const activityTokens = tokenize([
+    activity?.source,
+    activity?.kind,
+    activity?.label,
+    activity?.progress?.step,
+    activity?.progress?.phase,
+    activity?.progress?.currentStep,
+    activity?.progress?.template,
+    activity?.progress?.deliverable,
+  ].filter(Boolean).join(' '));
+  if (activityTokens.length === 0) return null;
+
+  const candidates = plan
+    .filter((step) => !step._activityKey || !actKey || step._activityKey === actKey)
+    .map((step) => ({
+      step,
+      score: matchScore(tokenize(step.description), activityTokens),
+    }))
+    .filter((item) => item.score > 0)
+    .sort((a, b) => {
+      if (b.score !== a.score) return b.score - a.score;
+      return statusRank(a.step.status) - statusRank(b.step.status);
+    });
+
+  return candidates[0]?.step ?? null;
+}
+
+function tokenize(value) {
+  return [
+    ...new Set(
+      String(value ?? '')
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .match(/[a-z0-9-]{4,}/g)
+        ?.filter((token) => !['production', 'running', 'queued', 'done', 'failed'].includes(token)) ?? [],
+    ),
+  ];
+}
+
+function matchScore(stepTokens, activityTokens) {
+  let score = 0;
+  for (const token of stepTokens) {
+    if (activityTokens.includes(token)) score += token === 'build' || token === 'polish' || token === 'export' || token === 'ingest' ? 4 : 1;
+  }
+  return score;
+}
+
+function statusRank(status) {
+  if (status === 'running') return 0;
+  if (status === 'pending') return 1;
+  if (status === 'done') return 2;
+  return 3;
+}

package/src/core/plan.test.js

@@ -0,0 +1,168 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { ensurePlanFromActivity, syncActivitiesToPlan, extractHeadlessPlan } from './plan.js';
+
+test('ensurePlanFromActivity: creates multi-step plan from activity.plan.steps', () => {
+  const session = { headlessPlan: null };
+  const activity = {
+    key: 'prod:job-1',
+    label: 'Pipeline',
+    plan: { steps: [{ id: 'build', label: 'Build' }, { id: 'polish', label: 'Polish' }] },
+    progress: {},
+  };
+  ensurePlanFromActivity(session, activity);
+  assert.equal(session.headlessPlan.length, 2);
+  assert.equal(session.headlessPlan[0].step, 1);
+  assert.equal(session.headlessPlan[0].id, 'build');
+  assert.equal(session.headlessPlan[0].description, 'Build');
+  assert.equal(session.headlessPlan[0].status, 'pending');
+  assert.equal(session.headlessPlan[0]._activityKey, 'prod:job-1');
+  assert.equal(session.headlessPlan[1].id, 'polish');
+});
+
+test('ensurePlanFromActivity: creates mono-step plan when no plan.steps', () => {
+  const session = { headlessPlan: null };
+  const activity = { key: 'prod:job-1', label: 'Build EAE', plan: null, progress: {} };
+  ensurePlanFromActivity(session, activity);
+  assert.equal(session.headlessPlan.length, 1);
+  assert.equal(session.headlessPlan[0].description, 'Build EAE');
+  assert.equal(session.headlessPlan[0]._activityKey, 'prod:job-1');
+});
+
+test('ensurePlanFromActivity: does not overwrite plan for same activity key', () => {
+  const existing = [{ step: 1, description: 'Existing', status: 'running', _activityKey: 'prod:job-1' }];
+  const session = { headlessPlan: existing };
+  const activity = { key: 'prod:job-1', label: 'Updated', plan: null, progress: {} };
+  ensurePlanFromActivity(session, activity);
+  assert.strictEqual(session.headlessPlan, existing);
+});
+
+test('ensurePlanFromActivity: replaces plan for different activity key', () => {
+  const existing = [{ step: 1, description: 'Old', status: 'done', _activityKey: 'prod:job-1' }];
+  const session = { headlessPlan: existing };
+  const activity = { key: 'prod:job-2', label: 'New Job', plan: null, progress: {} };
+  ensurePlanFromActivity(session, activity);
+  assert.notStrictEqual(session.headlessPlan, existing);
+  assert.equal(session.headlessPlan.length, 1);
+  assert.equal(session.headlessPlan[0].description, 'New Job');
+  assert.equal(session.headlessPlan[0]._activityKey, 'prod:job-2');
+});
+
+test('ensurePlanFromActivity: replaces null-key minimal plan for real activity', () => {
+  const minimal = [{ step: 1, description: 'cme.cme_export_run', status: 'running', _activityKey: null }];
+  const session = { headlessPlan: minimal };
+  const activity = { key: 'cme:export-1', label: 'CME Export', plan: null, progress: {} };
+  ensurePlanFromActivity(session, activity);
+  assert.notStrictEqual(session.headlessPlan, minimal);
+  assert.equal(session.headlessPlan[0].description, 'CME Export');
+  assert.equal(session.headlessPlan[0]._activityKey, 'cme:export-1');
+});
+
+test('ensurePlanFromActivity: no-op on null activity', () => {
+  const session = { headlessPlan: null };
+  ensurePlanFromActivity(session, null);
+  assert.equal(session.headlessPlan, null);
+});
+
+test('syncActivitiesToPlan: stepId sets correct step running, preceding pending→done', () => {
+  const plan = [
+    { step: 1, id: 'extract', description: 'Extract', status: 'pending' },
+    { step: 2, id: 'build', description: 'Build', status: 'pending' },
+    { step: 3, id: 'polish', description: 'Polish', status: 'pending' },
+  ];
+  syncActivitiesToPlan(plan, [{
+    key: 'prod:1', label: 'Build', status: 'running', terminal: false,
+    progress: { stepId: 'build' },
+  }]);
+  assert.equal(plan[0].status, 'done');
+  assert.equal(plan[1].status, 'running');
+  assert.equal(plan[2].status, 'pending');
+});
+
+test('syncActivitiesToPlan: stepIndex sets preceding steps done', () => {
+  const plan = [
+    { step: 1, description: 'Step 1', status: 'pending' },
+    { step: 2, description: 'Step 2', status: 'pending' },
+    { step: 3, description: 'Step 3', status: 'pending' },
+  ];
+  syncActivitiesToPlan(plan, [{
+    key: 'prod:1', label: 'Step 3', status: 'running', terminal: false,
+    progress: { stepIndex: 3 },
+  }]);
+  assert.equal(plan[0].status, 'done');
+  assert.equal(plan[1].status, 'done');
+  assert.equal(plan[2].status, 'running');
+});
+
+test('syncActivitiesToPlan: terminal success marks all activity steps done', () => {
+  const plan = [
+    { step: 1, id: 'build', description: 'Build', status: 'running', _activityKey: 'prod:1' },
+    { step: 2, id: 'polish', description: 'Polish', status: 'pending', _activityKey: 'prod:1' },
+  ];
+  syncActivitiesToPlan(plan, [{
+    key: 'prod:1', label: 'Pipeline', status: 'done', terminal: true,
+    progress: { stepId: 'build' },
+  }]);
+  assert.equal(plan[0].status, 'done');
+  assert.equal(plan[1].status, 'done');
+});
+
+test('syncActivitiesToPlan: terminal failed marks matched step failed, prior steps preserved', () => {
+  const plan = [
+    { step: 1, id: 'extract', description: 'Extract', status: 'done' },
+    { step: 2, id: 'build', description: 'Build', status: 'running' },
+    { step: 3, id: 'polish', description: 'Polish', status: 'pending' },
+  ];
+  syncActivitiesToPlan(plan, [{
+    key: 'prod:1', label: 'Build', status: 'failed', terminal: true,
+    progress: { stepId: 'build' },
+  }]);
+  assert.equal(plan[0].status, 'done');
+  assert.equal(plan[1].status, 'failed');
+  assert.equal(plan[2].status, 'pending');
+});
+
+test('syncActivitiesToPlan: failed step not repassed to done', () => {
+  const plan = [
+    { step: 1, id: 'build', description: 'Build', status: 'failed' },
+    { step: 2, id: 'polish', description: 'Polish', status: 'pending' },
+  ];
+  syncActivitiesToPlan(plan, [{
+    key: 'prod:1', label: 'Polish', status: 'done', terminal: true,
+    progress: { stepId: 'polish' },
+  }]);
+  assert.equal(plan[0].status, 'failed');
+  assert.equal(plan[1].status, 'done');
+});
+
+test('syncActivitiesToPlan: legacy text matching still works for old agents', () => {
+  const plan = [
+    { step: 1, description: 'ingest production content', status: 'pending' },
+    { step: 2, description: 'build output', status: 'pending' },
+  ];
+  syncActivitiesToPlan(plan, [{
+    key: 'prod:1', label: 'Production build', status: 'running',
+    source: 'production', kind: 'build', terminal: false, progress: {},
+  }]);
+  assert.equal(plan[0].status, 'done');
+  assert.equal(plan[1].status, 'running');
+});
+
+test('syncActivitiesToPlan: _activityKey mismatch prevents structured match', () => {
+  const plan = [
+    { step: 1, id: 'build', description: 'Build', status: 'pending', _activityKey: 'prod:job-A' },
+  ];
+  syncActivitiesToPlan(plan, [{
+    key: 'prod:job-B', label: 'Build', status: 'running', terminal: false,
+    progress: { stepId: 'build' },
+  }]);
+  assert.equal(plan[0].status, 'pending');
+});
+
+test('extractHeadlessPlan: parses numbered list from text (legacy)', () => {
+  const text = '1. CME export\n2. Build pipeline\n3. Send report';
+  const plan = extractHeadlessPlan(text);
+  assert.equal(plan.length, 3);
+  assert.equal(plan[0].description, 'CME export');
+  assert.equal(plan[1].step, 2);
+});

package/src/core/skills.js

@@ -0,0 +1,142 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+const SKILL_NAME_RE = /^[a-zA-Z0-9_-]{1,80}$/;
+const DEFAULT_UI_SKILL_DIR = '.wiki/skills';
+
+function parseFrontmatter(raw) {
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) return { meta: {}, body: raw.trim() };
+  const meta = {};
+  let inParams = false;
+  const params = [];
+  for (const line of match[1].split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    if (trimmed === 'params:') {
+      inParams = true;
+      continue;
+    }
+    if (inParams && trimmed.startsWith('- ')) {
+      params.push(trimmed.slice(2).trim());
+      continue;
+    }
+    inParams = false;
+    const sep = trimmed.indexOf(':');
+    if (sep === -1) continue;
+    meta[trimmed.slice(0, sep).trim()] = trimmed.slice(sep + 1).trim();
+  }
+  if (params.length) meta.params = params;
+  return { meta, body: match[2].trim() };
+}
+
+function readSkillFile(filePath, fallbackName, scope) {
+  const raw = readFileSync(filePath, 'utf8');
+  const { meta, body } = parseFrontmatter(raw);
+  const name = String(meta.name || fallbackName).trim();
+  if (!SKILL_NAME_RE.test(name)) return null;
+  return {
+    name,
+    description: String(meta.description || '').trim(),
+    params: Array.isArray(meta.params) ? meta.params : [],
+    body,
+    scope,
+    path: filePath,
+  };
+}
+
+function readOptionalText(filePath) {
+  if (!existsSync(filePath)) return '';
+  return readFileSync(filePath, 'utf8').trim();
+}
+
+function safeRelativeEntry(value, fallback) {
+  const text = String(value || fallback).trim();
+  if (!text || text.startsWith('/') || text.includes('..')) return fallback;
+  return text;
+}
+
+function readWorkspaceManifest(workspacePath) {
+  const manifestPath = join(workspacePath, 'skill.yaml');
+  if (!existsSync(manifestPath)) return null;
+  try {
+    const manifest = parseYaml(readFileSync(manifestPath, 'utf8'));
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) return null;
+    return { manifest, manifestPath };
+  } catch {
+    return null;
+  }
+}
+
+function readWorkspaceManifestSkill(workspacePath, loadedManifest = null) {
+  const loaded = loadedManifest ?? readWorkspaceManifest(workspacePath);
+  if (!loaded) return null;
+  const { manifest, manifestPath } = loaded;
+  const name = String(manifest.name || basename(workspacePath)).trim();
+  if (!SKILL_NAME_RE.test(name)) return null;
+  const entrypoints = manifest.entrypoints && typeof manifest.entrypoints === 'object'
+    ? manifest.entrypoints
+    : {};
+  const claude = safeRelativeEntry(entrypoints.claude, 'CLAUDE.md');
+  const body = readOptionalText(join(workspacePath, claude));
+  return {
+    name,
+    title: String(manifest.title || name).trim(),
+    description: String(manifest.description || '').trim(),
+    params: [],
+    body,
+    scope: 'workspace',
+    path: manifestPath,
+    manifest,
+    entrypoints,
+    version: manifest.version ? String(manifest.version) : null,
+    language: manifest.language ? String(manifest.language) : null,
+  };
+}
+
+function workspaceUiSkillDir(loadedManifest = null) {
+  if (!loadedManifest) return DEFAULT_UI_SKILL_DIR;
+  const { manifest } = loadedManifest;
+  const entrypoints = manifest?.entrypoints && typeof manifest.entrypoints === 'object'
+    ? manifest.entrypoints
+    : {};
+  return safeRelativeEntry(entrypoints.uiSkillDir, DEFAULT_UI_SKILL_DIR);
+}
+
+function collectDirectorySkills(dir, scope) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+    .flatMap((entry) => {
+      const filePath = join(dir, entry.name);
+      const skill = readSkillFile(filePath, basename(entry.name, '.md'), scope);
+      return skill ? [skill] : [];
+    });
+}
+
+export function listSkills(session = {}) {
+  const skills = [];
+  if (session.workspacePath) {
+    const loadedManifest = readWorkspaceManifest(session.workspacePath);
+    const manifestSkill = readWorkspaceManifestSkill(session.workspacePath, loadedManifest);
+    if (manifestSkill) skills.push(manifestSkill);
+    skills.push(...collectDirectorySkills(join(session.workspacePath, workspaceUiSkillDir(loadedManifest)), 'workspace'));
+  }
+
+  const byName = new Map();
+  for (const skill of skills) byName.set(skill.name, skill);
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function findSkill(session, name) {
+  return listSkills(session).find((skill) => skill.name === name) ?? null;
+}
+
+export function formatSkillsForAgent(session) {
+  const skills = listSkills(session);
+  if (!skills.length) return 'No skills discovered.';
+  return skills
+    .map((skill) => `/${skill.name}: ${skill.description || 'workflow skill'} (${skill.scope})`)
+    .join('\n');
+}

package/src/core/wikirc.js

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import YAML from 'yaml';
+
+const DEFAULT_WIKIRC = '.wikirc.yaml';
+
+export function listWikircProfiles(workspacePath) {
+  if (!workspacePath || !existsSync(workspacePath)) return [];
+
+  return readdirSync(workspacePath, { withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+    .filter((name) => name === DEFAULT_WIKIRC || name.startsWith(`${DEFAULT_WIKIRC}.`))
+    .sort((a, b) => {
+      if (a === DEFAULT_WIKIRC) return -1;
+      if (b === DEFAULT_WIKIRC) return 1;
+      return a.localeCompare(b);
+    })
+    .map((fileName) => ({
+      name: fileName === DEFAULT_WIKIRC ? 'default' : fileName.slice(`${DEFAULT_WIKIRC}.`.length),
+      fileName,
+      path: join(workspacePath, fileName),
+      default: fileName === DEFAULT_WIKIRC,
+    }));
+}
+
+export function resolveWikircProfile(workspacePath, profileName = 'default') {
+  const profiles = listWikircProfiles(workspacePath);
+  const normalized = profileName || 'default';
+  const found = profiles.find((profile) => profile.name === normalized || profile.fileName === normalized);
+  if (!found) {
+    const available = profiles.map((profile) => profile.name).join(', ') || 'aucun';
+    throw new Error(`profil wikirc introuvable: ${normalized} (disponibles: ${available})`);
+  }
+  return found;
+}
+
+export function loadWikircProfile(workspacePath, profileName = 'default') {
+  const profile = resolveWikircProfile(workspacePath, profileName);
+  const doc = YAML.parseDocument(readFileSync(profile.path, 'utf8'), {
+    schema: 'core',
+  });
+  if (doc.errors.length > 0) {
+    throw new Error(`wikirc YAML invalide: ${doc.errors[0].message}`);
+  }
+  const config = doc.toJSON();
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error('wikirc YAML invalide: objet attendu a la racine');
+  }
+  return { profile, config };
+}
+
+export function summarizeWikircConfig(profile, config) {
+  return {
+    profile: profile.name,
+    fileName: basename(profile.path),
+    language: config?.language ?? null,
+    provider: config?.llm?.provider ?? null,
+    model: config?.llm?.model ?? null,
+    baseUrl: config?.llm?.baseUrl ?? null,
+    hasApiKey: Boolean(config?.llm?.apiKey),
+    vectorEnabled: Boolean(config?.retrieval?.vector?.enabled),
+    embeddingModel: config?.retrieval?.vector?.embeddingModel ?? null,
+  };
+}

package/src/core/workspaces.js

@@ -0,0 +1,81 @@
+import { execFile } from 'node:child_process';
+import { existsSync, readdirSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { managerEnvFile, readEnvFile, userManagerDir } from './env.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(__dirname, '../..');
+const execFileAsync = promisify(execFile);
+
+export function managerRoot() {
+  return process.env.WIKI_MANAGER_ROOT
+    ? resolve(process.env.WIKI_MANAGER_ROOT)
+    : packageRoot;
+}
+
+export function workspacesDir() {
+  return process.env.WIKI_WORKSPACES_DIR
+    ? resolve(process.env.WIKI_WORKSPACES_DIR)
+    : join(userManagerDir(), 'workspaces');
+}
+
+export function listWorkspaces() {
+  const root = workspacesDir();
+  if (!existsSync(root)) return [];
+
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+    .flatMap((entry) => {
+      const registryPath = join(root, entry.name);
+      const envFile = join(registryPath, '.env');
+      if (!existsSync(envFile)) return [];
+      const env = readEnvFile(envFile);
+      const workspacePath = env.WIKI_WORKSPACE_PATH || registryPath;
+      return [
+        {
+          name: env.WORKSPACE_NAME || entry.name,
+          registryPath,
+          envFile,
+          workspacePath: realpathSync.native?.(workspacePath) ?? realpathSync(workspacePath),
+          env,
+        },
+      ];
+    });
+}
+
+export function findWorkspace(name) {
+  return listWorkspaces().find((workspace) => workspace.name === name);
+}
+
+function isValidWorkspaceName(name) {
+  return (
+    typeof name === 'string' &&
+    /^[a-zA-Z0-9][a-zA-Z0-9_.-]*[a-zA-Z0-9]$|^[a-zA-Z0-9]$/.test(name) &&
+    !name.includes('..')
+  );
+}
+
+export async function createWorkspace(name, targetPath = null, options = {}) {
+  if (!isValidWorkspaceName(name)) {
+    throw new Error('Usage: /workspace init <name> [path]');
+  }
+  const args = ['config', name];
+  if (targetPath) args.push(targetPath);
+  const { stdout, stderr } = await execFileAsync(
+    join(managerRoot(), 'wiki-workspace'),
+    args,
+    {
+      cwd: managerRoot(),
+      env: {
+        ...process.env,
+        WIKI_WORKSPACES_DIR: workspacesDir(),
+        WIKI_MANAGER_ENV_FILE: managerEnvFile(),
+      },
+      maxBuffer: options.maxBuffer ?? 1024 * 1024 * 8,
+      timeout: options.timeout ?? 600_000,
+    },
+  );
+  return [stdout, stderr].filter(Boolean).join('\n').trim();
+}