@syncular/cli 0.0.0-44

package/src/commands/doctor.tsx

@@ -0,0 +1,133 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import process from 'node:process';
+import { Box, renderToString, Text } from 'ink';
+import type { ReactElement } from 'react';
+
+interface DoctorCheck {
+  name: 'bun' | 'workspace' | 'git';
+  label: string;
+  ok: boolean;
+  detail: string;
+  hint: string;
+}
+
+function runDoctorChecks(cwd: string): DoctorCheck[] {
+  const checks: DoctorCheck[] = [];
+  const hasBun = typeof process.versions.bun === 'string';
+  const hasWorkspacePackageJson = existsSync(join(cwd, 'package.json'));
+
+  checks.push({
+    name: 'bun',
+    label: 'Bun runtime',
+    ok: hasBun,
+    detail: hasBun ? `Bun ${process.versions.bun}` : 'Bun runtime not detected',
+    hint: 'Run the CLI with Bun, for example: bun syncular doctor',
+  });
+
+  checks.push({
+    name: 'workspace',
+    label: 'Workspace package',
+    ok: hasWorkspacePackageJson,
+    detail: hasWorkspacePackageJson
+      ? 'package.json found'
+      : 'package.json not found in current directory',
+    hint: 'Run this command in the project root or package directory.',
+  });
+
+  let hasGitRepo = false;
+  let currentDir = cwd;
+  for (let index = 0; index < 8; index += 1) {
+    if (existsSync(join(currentDir, '.git'))) {
+      hasGitRepo = true;
+      break;
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+
+  checks.push({
+    name: 'git',
+    label: 'Git repository',
+    ok: hasGitRepo,
+    detail: hasGitRepo
+      ? 'git repository detected'
+      : 'git repository not detected near current directory',
+    hint: 'Initialize a git repository with: git init',
+  });
+
+  return checks;
+}
+
+function renderDoctorView(args: {
+  cwd: string;
+  checks: DoctorCheck[];
+}): ReactElement {
+  const passedCount = args.checks.reduce(
+    (count, check) => count + (check.ok ? 1 : 0),
+    0
+  );
+  const failedCount = args.checks.length - passedCount;
+  const labelWidth = args.checks.reduce(
+    (maxWidth, check) => Math.max(maxWidth, check.label.length),
+    0
+  );
+  const allPassed = failedCount === 0;
+
+  return (
+    <Box flexDirection="column">
+      <Text color="cyanBright" bold>
+        syncular doctor
+      </Text>
+      <Text color="gray">cwd: {args.cwd}</Text>
+      <Box marginTop={1} flexDirection="column">
+        {args.checks.map((check) => (
+          <Box key={check.name} flexDirection="column">
+            <Box>
+              <Text color={check.ok ? 'greenBright' : 'redBright'}>
+                {check.ok ? 'OK  ' : 'FAIL'}
+              </Text>
+              <Text> {check.label.padEnd(labelWidth)} </Text>
+              <Text color={check.ok ? 'gray' : 'white'}>{check.detail}</Text>
+            </Box>
+            {check.ok ? null : (
+              <Box marginLeft={6}>
+                <Text color="yellow">hint: </Text>
+                <Text color="yellowBright">{check.hint}</Text>
+              </Box>
+            )}
+          </Box>
+        ))}
+      </Box>
+      <Box marginTop={1}>
+        <Text color={allPassed ? 'greenBright' : 'yellowBright'}>
+          {allPassed
+            ? `All checks passed (${passedCount}/${args.checks.length}).`
+            : `Checks passed: ${passedCount}/${args.checks.length}.`}
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+
+export async function runDoctor(): Promise<number> {
+  const cwd = process.cwd();
+  const checks = runDoctorChecks(cwd);
+  const rendered = renderToString(
+    renderDoctorView({
+      cwd,
+      checks,
+    }),
+    {
+      columns: Math.max(process.stdout.columns ?? 120, 120),
+    }
+  );
+  process.stdout.write(rendered);
+  if (!rendered.endsWith('\n')) {
+    process.stdout.write('\n');
+  }
+  return checks.every((check) => check.ok) ? 0 : 1;
+}

package/src/commands/migrate.ts

@@ -0,0 +1,312 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { printError } from '../output';
+
+type ChecksumMismatchMode = 'error' | 'reset';
+
+interface MigrationStatusInput {
+  cwd: string;
+}
+
+interface MigrationUpInput extends MigrationStatusInput {
+  onChecksumMismatch: ChecksumMismatchMode;
+  dryRun: boolean;
+}
+
+interface MigrationStatusResult {
+  currentVersion: number;
+  targetVersion: number;
+  pendingVersions: number[];
+  trackingTable?: string;
+}
+
+interface MigrationUpResult {
+  appliedVersions: number[];
+  currentVersion: number;
+  wasReset?: boolean;
+  dryRun?: boolean;
+}
+
+interface MigrationAdapter {
+  status(input: MigrationStatusInput): Promise<MigrationStatusResult>;
+  up(input: MigrationUpInput): Promise<MigrationUpResult>;
+}
+
+interface SyncularCliConfig {
+  migrate?: {
+    adapter: string;
+    export?: string;
+  };
+}
+
+const DEFAULT_CONFIG_PATH = 'syncular.config.json';
+const DEFAULT_MIGRATE_EXPORT = 'migrationRunner';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function parseConfig(value: unknown): SyncularCliConfig | { error: string } {
+  if (!isRecord(value)) {
+    return { error: 'Config must be a JSON object.' };
+  }
+
+  const config: SyncularCliConfig = {};
+  const migrateValue = value.migrate;
+  if (migrateValue !== undefined) {
+    if (!isRecord(migrateValue)) {
+      return { error: 'Config field "migrate" must be an object.' };
+    }
+
+    const adapter = migrateValue.adapter;
+    const exportName = migrateValue.export;
+    if (typeof adapter !== 'string' || adapter.length === 0) {
+      return {
+        error: 'Config field "migrate.adapter" must be a non-empty string.',
+      };
+    }
+    if (
+      exportName !== undefined &&
+      (typeof exportName !== 'string' || exportName.length === 0)
+    ) {
+      return {
+        error:
+          'Config field "migrate.export" must be a non-empty string when provided.',
+      };
+    }
+
+    config.migrate = {
+      adapter,
+      ...(exportName ? { export: exportName } : {}),
+    };
+  }
+
+  return config;
+}
+
+async function loadConfig(
+  configPath: string
+): Promise<{ config: SyncularCliConfig } | { error: string }> {
+  let raw = '';
+  try {
+    raw = await readFile(configPath, 'utf8');
+  } catch {
+    return {
+      error: `Config not found at ${configPath}. Run "syncular create --template syncular-libraries" first.`,
+    };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { error: `Config at ${configPath} is not valid JSON.` };
+  }
+
+  const normalized = parseConfig(parsed);
+  if ('error' in normalized) {
+    return { error: `${normalized.error} (path: ${configPath})` };
+  }
+
+  return { config: normalized };
+}
+
+function isMigrationAdapter(value: unknown): value is MigrationAdapter {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return typeof value.status === 'function' && typeof value.up === 'function';
+}
+
+async function loadMigrationAdapter(args: {
+  configPath: string;
+}): Promise<{ adapter: MigrationAdapter } | { error: string }> {
+  const loaded = await loadConfig(args.configPath);
+  if ('error' in loaded) {
+    return loaded;
+  }
+
+  const migrate = loaded.config.migrate;
+  if (!migrate) {
+    return {
+      error:
+        'Config does not define "migrate". Run "syncular create --template syncular-libraries" to scaffold adapter files.',
+    };
+  }
+
+  const adapterModulePath = resolve(dirname(args.configPath), migrate.adapter);
+  const adapterExportName = migrate.export ?? DEFAULT_MIGRATE_EXPORT;
+
+  let moduleValue: unknown;
+  try {
+    moduleValue = await import(pathToFileURL(adapterModulePath).href);
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      error: `Failed to load migrate adapter module (${adapterModulePath}): ${message}`,
+    };
+  }
+
+  if (!isRecord(moduleValue)) {
+    return {
+      error: `Adapter module ${adapterModulePath} did not load as an object module.`,
+    };
+  }
+
+  const exportValue = moduleValue[adapterExportName];
+  if (!isMigrationAdapter(exportValue)) {
+    return {
+      error:
+        `Adapter export "${adapterExportName}" in ${adapterModulePath} is missing ` +
+        'required methods: status() and up().',
+    };
+  }
+
+  return { adapter: exportValue };
+}
+
+function optionalFlag(
+  flagValues: Map<string, string>,
+  flag: string,
+  fallback: string
+): string {
+  const value = flagValues.get(flag)?.trim();
+  return value && value.length > 0 ? value : fallback;
+}
+
+function optionalBooleanFlag(
+  flagValues: Map<string, string>,
+  flag: string,
+  fallback: boolean
+): boolean {
+  const value = flagValues.get(flag);
+  if (!value) {
+    return fallback;
+  }
+
+  const normalized = value.trim().toLowerCase();
+  if (
+    normalized === '1' ||
+    normalized === 'true' ||
+    normalized === 'yes' ||
+    normalized === 'on'
+  ) {
+    return true;
+  }
+  if (
+    normalized === '0' ||
+    normalized === 'false' ||
+    normalized === 'no' ||
+    normalized === 'off'
+  ) {
+    return false;
+  }
+
+  throw new Error(
+    `Invalid ${flag} value "${value}". Use true/false, yes/no, on/off, or 1/0.`
+  );
+}
+
+function parseChecksumMode(
+  flagValues: Map<string, string>
+): ChecksumMismatchMode | { error: string } {
+  const value = flagValues.get('--on-checksum-mismatch');
+  if (!value) {
+    return 'error';
+  }
+  if (value === 'error' || value === 'reset') {
+    return value;
+  }
+  return {
+    error: 'Invalid value for --on-checksum-mismatch. Use "error" or "reset".',
+  };
+}
+
+function resolveConfigPath(
+  flagValues: Map<string, string>,
+  cwd: string
+): string {
+  const configPath = optionalFlag(flagValues, '--config', DEFAULT_CONFIG_PATH);
+  return resolve(cwd, configPath);
+}
+
+export async function runMigrateStatus(
+  flagValues: Map<string, string>
+): Promise<number> {
+  try {
+    const cwd = process.cwd();
+    const configPath = resolveConfigPath(flagValues, cwd);
+    const loaded = await loadMigrationAdapter({ configPath });
+    if ('error' in loaded) {
+      throw new Error(loaded.error);
+    }
+
+    const result = await loaded.adapter.status({ cwd });
+    const pendingVersions =
+      result.pendingVersions.length === 0
+        ? '(none)'
+        : result.pendingVersions.join(', ');
+
+    console.log(`Current version: ${result.currentVersion}`);
+    console.log(`Target version: ${result.targetVersion}`);
+    console.log(`Pending versions: ${pendingVersions}`);
+    if (result.trackingTable) {
+      console.log(`Tracking table: ${result.trackingTable}`);
+    }
+    return 0;
+  } catch (error: unknown) {
+    printError(
+      error instanceof Error ? error.message : 'Migration status failed.'
+    );
+    return 1;
+  }
+}
+
+export async function runMigrateUp(
+  flagValues: Map<string, string>
+): Promise<number> {
+  try {
+    const checksumMode = parseChecksumMode(flagValues);
+    if (typeof checksumMode !== 'string') {
+      throw new Error(checksumMode.error);
+    }
+
+    const confirmReset = optionalBooleanFlag(flagValues, '--yes', false);
+    if (checksumMode === 'reset' && !confirmReset) {
+      throw new Error(
+        'Reset mode requires explicit confirmation. Re-run with --on-checksum-mismatch reset --yes true.'
+      );
+    }
+
+    const cwd = process.cwd();
+    const dryRun = optionalBooleanFlag(flagValues, '--dry-run', false);
+    const configPath = resolveConfigPath(flagValues, cwd);
+    const loaded = await loadMigrationAdapter({ configPath });
+    if ('error' in loaded) {
+      throw new Error(loaded.error);
+    }
+
+    const result = await loaded.adapter.up({
+      cwd,
+      onChecksumMismatch: checksumMode,
+      dryRun,
+    });
+    const appliedVersions =
+      result.appliedVersions.length === 0
+        ? '(none)'
+        : result.appliedVersions.join(', ');
+
+    console.log(`Applied versions: ${appliedVersions}`);
+    console.log(`Current version: ${result.currentVersion}`);
+    console.log(`Checksum mismatch mode: ${checksumMode}`);
+    console.log(`Reset occurred: ${result.wasReset ? 'yes' : 'no'}`);
+    if (result.dryRun || dryRun) {
+      console.log('Dry run: yes');
+    }
+    return 0;
+  } catch (error: unknown) {
+    printError(error instanceof Error ? error.message : 'Migration up failed.');
+    return 1;
+  }
+}