neondeck 1.0.0-beta.10

package/src/modules/commands/handlers/repo.ts

@@ -0,0 +1,339 @@
+import {
+  readGitDiffSummary,
+  readGitRepoStatus,
+  readRepoRegistrySnapshot,
+  repoFullName,
+} from '../../repos';
+import type { RuntimePaths } from '../../../runtime-home';
+import type { NeonCommandResult, ParsedNeonCommand } from '../schemas';
+import { completedCommand, failedCommand } from '../summaries';
+
+export async function repoStatusCommand(
+  command: ParsedNeonCommand,
+  paths: RuntimePaths,
+): Promise<NeonCommandResult> {
+  const registry = await readRepoRegistrySnapshot(paths);
+  const target = command.args[0];
+  const repos = target
+    ? registry.repos.filter(
+        (repo) =>
+          repo.id === target ||
+          repoFullName(repo).toLowerCase() === target.toLowerCase(),
+      )
+    : registry.repos;
+
+  if (target && repos.length === 0) {
+    return failedCommand(
+      command.name,
+      command.raw,
+      `Repository "${target}" is not configured.`,
+      { requires: ['repo'] },
+    );
+  }
+
+  const statuses = await Promise.all(repos.map(readGitRepoStatus));
+  return completedCommand(
+    command.name,
+    command.raw,
+    repos.length === 0
+      ? 'No repositories are configured.'
+      : `Checked ${statuses.length} configured repositor${
+          statuses.length === 1 ? 'y' : 'ies'
+        }.`,
+    {
+      home: registry.home,
+      repos: statuses,
+      attention: statuses.filter((repo) => repo.dirty || repo.error),
+    },
+  );
+}
+
+export async function draftPrDescriptionCommand(
+  command: ParsedNeonCommand,
+  paths: RuntimePaths,
+): Promise<NeonCommandResult> {
+  const resolved = await resolveCommandRepo(command, paths);
+  if (!resolved.ok) {
+    return failedCommand(command.name, command.raw, resolved.message, {
+      requires: resolved.requires,
+      data: resolved.data,
+    });
+  }
+
+  const health = await readGitRepoStatus(resolved.repo);
+  const draft = {
+    title: `${resolved.repo.id}: <short change summary>`,
+    body: [
+      '## Summary',
+      '- <what changed>',
+      '',
+      '## Validation',
+      ...validationChecklist(resolved.repo).map((item) => `- [ ] ${item}`),
+      '',
+      '## Risk',
+      `- Working tree: ${health.dirty ? `${health.changeCount} uncommitted change${health.changeCount === 1 ? '' : 's'}` : 'clean'}`,
+      `- Branch: ${health.branch ?? 'unknown'} -> ${resolved.repo.defaultBranch}`,
+    ].join('\n'),
+  };
+
+  return completedCommand(
+    command.name,
+    command.raw,
+    `Prepared a PR description scaffold for ${resolved.repo.id}.`,
+    {
+      repo: resolved.repo,
+      health,
+      draft,
+      assistantBrief:
+        'Use this scaffold as a draft only. Ask for diff details or run local review before making specific claims about changed behavior.',
+    },
+  );
+}
+
+export async function preparePrCommand(
+  command: ParsedNeonCommand,
+  paths: RuntimePaths,
+): Promise<NeonCommandResult> {
+  const resolved = await resolveCommandRepo(command, paths);
+  if (!resolved.ok) {
+    return failedCommand(command.name, command.raw, resolved.message, {
+      requires: resolved.requires,
+      data: resolved.data,
+    });
+  }
+
+  const health = await readGitRepoStatus(resolved.repo);
+  const checks = preparePrChecks(resolved.repo, health);
+
+  return completedCommand(
+    command.name,
+    command.raw,
+    `Prepared PR readiness checklist for ${resolved.repo.id}.`,
+    {
+      repo: resolved.repo,
+      health,
+      checks,
+      ready: checks.every((item) => item.status === 'ok'),
+      assistantBrief:
+        'Use these deterministic readiness checks before recommending PR creation. Do not run host commands unless a future approved action exists.',
+    },
+  );
+}
+
+export async function reviewLocalCommand(
+  command: ParsedNeonCommand,
+  paths: RuntimePaths,
+): Promise<NeonCommandResult> {
+  const resolved = await resolveCommandRepo(command, paths);
+  if (!resolved.ok) {
+    return failedCommand(command.name, command.raw, resolved.message, {
+      requires: resolved.requires,
+      data: resolved.data,
+    });
+  }
+
+  const health = await readGitRepoStatus(resolved.repo);
+  const diff = await readGitDiffSummary(resolved.repo);
+  const findings = localReviewFindings(resolved.repo, health, diff);
+
+  return completedCommand(
+    command.name,
+    command.raw,
+    findings.length > 0
+      ? `Found ${findings.length} local review finding${findings.length === 1 ? '' : 's'} for ${resolved.repo.id}.`
+      : `No deterministic local review findings for ${resolved.repo.id}.`,
+    {
+      repo: resolved.repo,
+      health,
+      diff,
+      findings,
+      assistantBrief:
+        'Lead with these deterministic local findings and diff metadata. This is still not a semantic code review because file contents were not read by this command.',
+    },
+  );
+}
+
+export async function resolveCommandRepo(
+  command: ParsedNeonCommand,
+  paths: RuntimePaths,
+): Promise<
+  | {
+      ok: true;
+      repo: Awaited<
+        ReturnType<typeof readRepoRegistrySnapshot>
+      >['repos'][number];
+    }
+  | {
+      ok: false;
+      message: string;
+      requires?: string[];
+      data?: unknown;
+    }
+> {
+  const registry = await readRepoRegistrySnapshot(paths);
+  const target = command.args.join(' ').trim();
+  if (registry.repos.length === 0) {
+    return {
+      ok: false,
+      message: 'No repositories are configured.',
+      requires: ['repo'],
+    };
+  }
+
+  if (!target) {
+    if (registry.repos.length === 1) {
+      return { ok: true, repo: registry.repos[0] };
+    }
+
+    return {
+      ok: false,
+      message: 'A repository id or owner/repo is required.',
+      requires: ['repo'],
+      data: { repos: registry.repos.map((repo) => repo.id) },
+    };
+  }
+
+  const repo = registry.repos.find(
+    (item) =>
+      item.id === target ||
+      item.github.name === target ||
+      repoFullName(item).toLowerCase() === target.toLowerCase(),
+  );
+  if (!repo) {
+    return {
+      ok: false,
+      message: `Repository "${target}" is not configured.`,
+      requires: ['repo'],
+      data: { repos: registry.repos.map((item) => item.id) },
+    };
+  }
+
+  return { ok: true, repo };
+}
+
+export function validationChecklist(
+  repo: Awaited<ReturnType<typeof readRepoRegistrySnapshot>>['repos'][number],
+) {
+  const scripts = repo.packageScripts ?? {};
+  const preferred = ['format:check', 'lint', 'typecheck', 'test', 'check'];
+  const available = preferred.filter((script) => scripts[script]);
+  if (available.length > 0) {
+    return available.map((script) => `npm run ${script}`);
+  }
+
+  return ['Run the project validation command for this repo.'];
+}
+
+export function preparePrChecks(
+  repo: Awaited<ReturnType<typeof readRepoRegistrySnapshot>>['repos'][number],
+  health: Awaited<ReturnType<typeof readGitRepoStatus>>,
+) {
+  return [
+    {
+      id: 'working-tree',
+      status: health.error || health.dirty ? 'attention' : 'ok',
+      message: health.error
+        ? `Git status failed: ${health.error}`
+        : health.dirty
+          ? `${health.changeCount} local change${health.changeCount === 1 ? '' : 's'} need review before PR creation.`
+          : 'Working tree is clean.',
+    },
+    {
+      id: 'branch',
+      status:
+        health.branch && health.branch !== repo.defaultBranch
+          ? 'ok'
+          : 'attention',
+      message: health.branch
+        ? health.branch === repo.defaultBranch
+          ? `Current branch is the default branch (${repo.defaultBranch}).`
+          : `Current branch is ${health.branch}.`
+        : 'Current branch is unknown.',
+    },
+    {
+      id: 'upstream',
+      status:
+        health.ahead === null && health.behind === null ? 'attention' : 'ok',
+      message:
+        health.ahead === null && health.behind === null
+          ? 'No upstream tracking branch was detected.'
+          : `Ahead ${health.ahead ?? 0}, behind ${health.behind ?? 0}.`,
+    },
+    {
+      id: 'validation',
+      status: 'attention',
+      message: `Run validation before opening PR: ${validationChecklist(repo).join(', ')}.`,
+    },
+  ];
+}
+
+export function localReviewFindings(
+  repo: Awaited<ReturnType<typeof readRepoRegistrySnapshot>>['repos'][number],
+  health: Awaited<ReturnType<typeof readGitRepoStatus>>,
+  diff: Awaited<ReturnType<typeof readGitDiffSummary>>,
+) {
+  const findings: Array<{
+    severity: 'high' | 'medium' | 'low';
+    title: string;
+    message: string;
+  }> = [];
+
+  if (health.error) {
+    findings.push({
+      severity: 'high',
+      title: 'Git status unavailable',
+      message: health.error,
+    });
+    return findings;
+  }
+
+  if (health.branch === repo.defaultBranch) {
+    findings.push({
+      severity: 'medium',
+      title: 'Working on default branch',
+      message: `Current branch is ${repo.defaultBranch}; create a topic branch before PR prep.`,
+    });
+  }
+
+  if (health.behind && health.behind > 0) {
+    findings.push({
+      severity: 'medium',
+      title: 'Branch is behind upstream',
+      message: `Branch is ${health.behind} commit${health.behind === 1 ? '' : 's'} behind upstream.`,
+    });
+  }
+
+  if (health.dirty) {
+    findings.push({
+      severity: 'low',
+      title: 'Uncommitted changes present',
+      message: `${health.changeCount} local change${health.changeCount === 1 ? '' : 's'} detected: ${health.changes.slice(0, 5).join(', ')}`,
+    });
+  }
+
+  if (!diff.ok) {
+    findings.push({
+      severity: 'medium',
+      title: 'Diff summary unavailable',
+      message: diff.error ?? 'Could not read git diff metadata.',
+    });
+  }
+
+  if (diff.fileCount > 15) {
+    findings.push({
+      severity: 'medium',
+      title: 'Large local diff',
+      message: `${diff.fileCount} files changed with ${diff.additions} additions and ${diff.deletions} deletions.`,
+    });
+  }
+
+  if (diff.binaryFiles > 0) {
+    findings.push({
+      severity: 'low',
+      title: 'Binary files changed',
+      message: `${diff.binaryFiles} changed file${diff.binaryFiles === 1 ? ' is' : 's are'} binary or uncounted by git numstat.`,
+    });
+  }
+
+  return findings;
+}

package/src/modules/commands/index.ts

@@ -0,0 +1,5 @@
+export * from './actions';
+export * from './registry';
+export * from './runner';
+export * from './schemas';
+export { inferWatchPrReferenceFromSession } from './handlers/misc';

package/src/modules/commands/registry.ts

@@ -0,0 +1,157 @@
+import type { NeonCommandName, ParsedNeonCommand } from './schemas';
+
+export function supportedCommands() {
+  return [
+    {
+      name: 'repo-status',
+      usage: '/repo-status [repo-id]',
+      description: 'Inspect local git status for configured repositories.',
+    },
+    {
+      name: 'review-queue',
+      usage: '/review-queue',
+      description: 'Fetch and summarize the configured GitHub PR queue.',
+    },
+    {
+      name: 'review-pr',
+      usage: '/review-pr <repo#number|owner/repo#number|url>',
+      description:
+        'Prepare local PR review reports and Neon-origin draft comments for a human reviewer.',
+    },
+    {
+      name: 'fix-ci',
+      usage: '/fix-ci [repo#number|owner/repo#number]',
+      description:
+        'Queue a bounded CI fix workflow for a PR with failing checks.',
+    },
+    {
+      name: 'explain-ci',
+      usage: '/explain-ci [--report] [repo#number|owner/repo#number]',
+      description:
+        'Explain deterministic CI/check status for a PR before agent reasoning, optionally writing a local dossier report.',
+    },
+    {
+      name: 'summarize-pr',
+      usage: '/summarize-pr [repo#number|owner/repo#number]',
+      description: 'Summarize PR facts from the GitHub queue.',
+    },
+    {
+      name: 'draft-pr-description',
+      usage: '/draft-pr-description [repo-id|owner/repo]',
+      description:
+        'Draft a PR description scaffold from local repo status and configured metadata.',
+    },
+    {
+      name: 'prepare-pr',
+      usage: '/prepare-pr [repo-id|owner/repo]',
+      description:
+        'Prepare a local repo for PR creation with deterministic readiness checks.',
+    },
+    {
+      name: 'review-local',
+      usage: '/review-local [repo-id|owner/repo]',
+      description:
+        'Review local working tree status and call out deterministic risks.',
+    },
+    {
+      name: 'briefing',
+      usage: '/briefing',
+      description:
+        'Summarize repos, watches, scheduled tasks, notifications, and PR queue readiness.',
+    },
+    {
+      name: 'reasoning',
+      usage: '/reasoning [off|minimal|low|medium|high|xhigh]',
+      description:
+        'Show or change the active Neon session reasoning level for the selected display model.',
+    },
+    {
+      name: 'memory',
+      usage:
+        '/memory [scope] | /memory learn <user|local|project> <key> <json-or-text> | /memory archive <scope> <key>',
+      description:
+        'List or mutate durable structured memory through typed memory actions.',
+    },
+    {
+      name: 'watch-pr',
+      usage: '/watch-pr <repo#number|owner/repo#number|url>',
+      description: 'Create a persistent PR watch.',
+    },
+    {
+      name: 'dev-doctor',
+      usage: '/dev-doctor',
+      description:
+        'Inspect local repo, package, env, port, server, and database health.',
+    },
+  ];
+}
+
+export function parseNeonCommand(
+  input: string,
+):
+  | { ok: true; command: ParsedNeonCommand }
+  | { ok: false; error: string; requires?: string[] } {
+  const trimmed = input.trim();
+  if (!trimmed.startsWith('/')) {
+    return {
+      ok: false,
+      error: 'Neon commands must start with slash.',
+      requires: ['command'],
+    };
+  }
+
+  const [head, ...args] = splitCommand(trimmed.slice(1));
+  if (!head) {
+    return {
+      ok: false,
+      error: 'A command name is required.',
+      requires: ['command'],
+    };
+  }
+
+  if (!isCommandName(head)) {
+    return {
+      ok: false,
+      error: `Unknown Neon command "/${head}".`,
+      requires: ['supportedCommand'],
+    };
+  }
+
+  return {
+    ok: true,
+    command: {
+      name: head,
+      args,
+      raw: trimmed,
+    },
+  };
+}
+
+export function splitCommand(input: string) {
+  const parts = input.match(/"[^"]*"|'[^']*'|\S+/g) ?? [];
+  return parts.map((part) =>
+    (part.startsWith('"') && part.endsWith('"')) ||
+    (part.startsWith("'") && part.endsWith("'"))
+      ? part.slice(1, -1)
+      : part,
+  );
+}
+
+export function isCommandName(value: string): value is NeonCommandName {
+  return [
+    'repo-status',
+    'review-queue',
+    'review-pr',
+    'fix-ci',
+    'explain-ci',
+    'summarize-pr',
+    'draft-pr-description',
+    'prepare-pr',
+    'review-local',
+    'briefing',
+    'reasoning',
+    'memory',
+    'watch-pr',
+    'dev-doctor',
+  ].includes(value);
+}

package/src/modules/commands/runner.ts

@@ -0,0 +1,152 @@
+import * as v from 'valibot';
+import { addWorkflowSummary } from '../app-state';
+import {
+  ensureRuntimeHome,
+  runtimePaths,
+  type RuntimePaths,
+} from '../../runtime-home';
+import type {
+  CommandExecutionContext,
+  CommandDependencies,
+  NeonCommandResult,
+  ParsedNeonCommand,
+} from './schemas';
+import { commandRunInputSchema } from './schemas';
+import { parseNeonCommand } from './registry';
+import {
+  briefingCommand,
+  devDoctorCommand,
+  draftPrDescriptionCommand,
+  explainCiCommand,
+  fixCiCommand,
+  memoryCommand,
+  preparePrCommand,
+  reasoningCommand,
+  repoStatusCommand,
+  reviewPrCommand,
+  reviewLocalCommand,
+  reviewQueueCommand,
+  summarizePrCommand,
+  watchPrCommand,
+} from './handlers';
+import { compactCommandSummary, failedCommand } from './summaries';
+
+export async function runNeonCommand(
+  input: v.InferInput<typeof commandRunInputSchema>,
+  paths = runtimePaths(),
+  dependencies: CommandDependencies = {},
+): Promise<NeonCommandResult> {
+  await ensureRuntimeHome(paths);
+  const parsedInput = v.safeParse(commandRunInputSchema, input);
+  if (!parsedInput.success) {
+    return failedCommand('repo-status', '', 'Invalid command input.', {
+      errors: [v.summarize(parsedInput.issues)],
+    });
+  }
+
+  const parsed = parseNeonCommand(parsedInput.output.command);
+  if (!parsed.ok) {
+    return failedCommand(
+      'repo-status',
+      parsedInput.output.command,
+      parsed.error,
+      {
+        requires: parsed.requires,
+      },
+    );
+  }
+
+  const context: CommandExecutionContext = {
+    sessionId: parsedInput.output.sessionId,
+    surface: parsedInput.output.surface,
+  };
+  const result = await executeCommand(
+    parsed.command,
+    paths,
+    dependencies,
+    context,
+  );
+  const runId = commandWorkflowRunId(result);
+  const workflowSummary = await addWorkflowSummary(
+    {
+      workflow: `command:${parsed.command.name}`,
+      ...(runId ? { runId } : {}),
+      status: result.status,
+      summary: compactCommandSummary(result),
+    },
+    paths,
+  );
+
+  return {
+    ...result,
+    workflowSummary,
+  };
+}
+
+async function executeCommand(
+  command: ParsedNeonCommand,
+  paths: RuntimePaths,
+  dependencies: CommandDependencies,
+  context: CommandExecutionContext,
+): Promise<NeonCommandResult> {
+  if (command.name === 'repo-status') {
+    return repoStatusCommand(command, paths);
+  }
+
+  if (command.name === 'review-queue') {
+    return reviewQueueCommand(command, paths, dependencies);
+  }
+
+  if (command.name === 'review-pr') {
+    return reviewPrCommand(command, paths, dependencies);
+  }
+
+  if (command.name === 'fix-ci') {
+    return fixCiCommand(command, paths, dependencies);
+  }
+
+  if (command.name === 'explain-ci') {
+    return explainCiCommand(command, paths, dependencies);
+  }
+
+  if (command.name === 'summarize-pr') {
+    return summarizePrCommand(command, paths, dependencies);
+  }
+
+  if (command.name === 'draft-pr-description') {
+    return draftPrDescriptionCommand(command, paths);
+  }
+
+  if (command.name === 'prepare-pr') {
+    return preparePrCommand(command, paths);
+  }
+
+  if (command.name === 'review-local') {
+    return reviewLocalCommand(command, paths);
+  }
+
+  if (command.name === 'briefing') {
+    return briefingCommand(command, paths, dependencies);
+  }
+
+  if (command.name === 'reasoning') {
+    return reasoningCommand(command, paths);
+  }
+
+  if (command.name === 'memory') {
+    return memoryCommand(command, paths);
+  }
+
+  if (command.name === 'watch-pr') {
+    return watchPrCommand(command, paths, dependencies, context);
+  }
+
+  return devDoctorCommand(command, paths);
+}
+
+function commandWorkflowRunId(result: NeonCommandResult) {
+  if (!result.data || typeof result.data !== 'object') return null;
+  if (!('runId' in result.data)) return null;
+  const runId = result.data.runId;
+  return typeof runId === 'string' && runId.trim() ? runId : null;
+}