create-threadlens-app 0.1.0

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "create-threadlens-app",
+  "version": "0.1.0",
+  "description": "One-command local-first ThreadLens self-host installer",
+  "license": "BUSL-1.1",
+  "type": "module",
+  "bin": {
+    "create-threadlens-app": "src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "vitest": "^1.6.0"
+  }
+}

package/src/args.js

@@ -0,0 +1,80 @@
+const MANAGEMENT_COMMANDS = new Set(['start', 'stop', 'restart', 'status', 'logs', 'doctor', 'upgrade', 'reset']);
+const SUPPORTED_PROFILES = new Set(['prod', 'dev']);
+
+export function parseArgs(argv) {
+  const args = [...argv];
+  const first = args[0];
+  const command = MANAGEMENT_COMMANDS.has(first) ? args.shift() : 'install';
+  const options = {
+    command,
+    directory: command === 'install' ? 'threadlens' : undefined,
+    yes: false,
+    port: 4749,
+    portMode: 'fixed',
+    name: undefined,
+    profile: 'prod',
+    open: true,
+    verbose: false,
+    webPort: undefined,
+    apiPort: undefined,
+    resetMode: undefined,
+  };
+
+  if (command === 'reset' && args[0] && !args[0].startsWith('-')) {
+    options.resetMode = args.shift();
+  }
+
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === '--yes' || token === '-y') {
+      options.yes = true;
+    } else if (token === '--port') {
+      const value = requireValue(token, args.shift());
+      if (value === 'auto') {
+        options.port = 4749;
+        options.portMode = 'auto';
+      } else {
+        options.port = parsePort(value);
+        options.portMode = 'fixed';
+      }
+    } else if (token === '--name') {
+      options.name = requireValue(token, args.shift());
+    } else if (token === '--profile') {
+      const profile = requireValue(token, args.shift());
+      if (!SUPPORTED_PROFILES.has(profile)) throw new Error(`Unsupported profile: ${profile}`);
+      options.profile = profile;
+    } else if (token === '--web-port') {
+      options.webPort = parsePort(requireValue(token, args.shift()));
+    } else if (token === '--api-port') {
+      options.apiPort = parsePort(requireValue(token, args.shift()));
+    } else if (token === '--no-open') {
+      options.open = false;
+    } else if (token === '--verbose') {
+      options.verbose = true;
+    } else if (token.startsWith('-')) {
+      throw new Error(`Unknown option: ${token}`);
+    } else if (command === 'install') {
+      options.directory = token;
+    } else {
+      throw new Error(`Unexpected argument for ${command}: ${token}`);
+    }
+  }
+
+  if (options.profile === 'dev') {
+    options.webPort = options.webPort ?? 4748;
+    options.apiPort = options.apiPort ?? options.port;
+  }
+
+  return options;
+}
+
+function requireValue(flag, value) {
+  if (!value || value.startsWith('-')) throw new Error(`Missing value for ${flag}`);
+  return value;
+}
+
+function parsePort(value) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`Invalid port: ${value}`);
+  return port;
+}

package/src/commands.js

@@ -0,0 +1,104 @@
+import { readFile } from 'node:fs/promises';
+import { checkDocker, defaultRun, logsCompose, resetDataVolume, startCompose, statusCompose, stopCompose } from './docker.js';
+import { waitForReady as defaultWaitForReady } from './health.js';
+import { readManifest, readState, updateState } from './manifest.js';
+import { CliError, createLogger } from './output.js';
+
+export async function runCommand(options, deps = {}) {
+  const cwd = deps.cwd ?? process.cwd();
+  const logger = deps.logger ?? createLogger({ verbose: options.verbose });
+  const run = deps.run ?? defaultRun;
+  const waitForReady = deps.waitForReady ?? defaultWaitForReady;
+  const manifest = await readManifest(cwd);
+
+  if (options.command === 'start') {
+    await checkDocker({ run });
+    await startCompose(manifest, { run, stream: options.verbose });
+    await waitForReady({ apiUrl: `http://localhost:${manifest.ports.api}`, webUrl: `http://localhost:${manifest.ports.web}` });
+    await updateState(cwd, { status: 'running', lastStartedAt: new Date().toISOString() });
+    logger.success(`ThreadLens is running at http://localhost:${manifest.ports.app}`);
+    return;
+  }
+
+  if (options.command === 'stop') {
+    await stopCompose(manifest, { run });
+    await updateState(cwd, { status: 'stopped', lastStoppedAt: new Date().toISOString() });
+    logger.success('ThreadLens stopped. Data volume was preserved.');
+    return;
+  }
+
+  if (options.command === 'restart') {
+    await stopCompose(manifest, { run });
+    await startCompose(manifest, { run, stream: options.verbose });
+    await waitForReady({ apiUrl: `http://localhost:${manifest.ports.api}`, webUrl: `http://localhost:${manifest.ports.web}` });
+    await updateState(cwd, { status: 'running', lastStartedAt: new Date().toISOString() });
+    logger.success(`ThreadLens restarted at http://localhost:${manifest.ports.app}`);
+    return;
+  }
+
+  if (options.command === 'status') {
+    const result = await statusCompose(manifest, { run });
+    logger.info(result.stdout || 'No Compose status output.');
+    return;
+  }
+
+  if (options.command === 'logs') {
+    await logsCompose(manifest, { run });
+    return;
+  }
+
+  if (options.command === 'doctor') {
+    await doctor(cwd, manifest, { logger, run, waitForReady });
+    return;
+  }
+
+  if (options.command === 'upgrade') {
+    const state = await readState(cwd);
+    await updateState(cwd, {
+      status: state.status ?? 'unknown',
+      currentVersion: manifest.threadlensVersion,
+      previousVersion: state.previousVersion ?? null,
+    });
+    logger.success(`This instance is already on ThreadLens ${manifest.threadlensVersion}. Future versions will update compose.yml, restart, and re-run readiness checks.`);
+    return;
+  }
+
+  if (options.command === 'reset') {
+    await reset(options, cwd, manifest, { logger, run });
+    return;
+  }
+
+  throw new CliError('unknown_command', `Unknown command: ${options.command}`, 1);
+}
+
+async function doctor(cwd, manifest, { logger, run, waitForReady }) {
+  logger.step('ThreadLens doctor');
+  logger.info(`Directory: ${cwd}`);
+  logger.info(`Compose project: ${manifest.composeProject}`);
+  logger.info(`Data volume: ${manifest.volumeName}`);
+  logger.info(`App URL: http://localhost:${manifest.ports.app}`);
+  await checkDocker({ run });
+  logger.success('Docker and Compose are available');
+
+  const env = await readFile(`${cwd}/.env`, 'utf8').catch(() => '');
+  for (const key of ['ANTHROPIC_API_KEY', 'GEMINI_API_KEY', 'PARALLEL_API_KEY', 'BLUESKY_HANDLE', 'BLUESKY_APP_PASSWORD']) {
+    const match = env.match(new RegExp(`^${key}=(.*)$`, 'm'));
+    logger.info(`${key}: ${match && match[1] ? 'set' : 'empty'}`);
+  }
+
+  await waitForReady({ apiUrl: `http://localhost:${manifest.ports.api}`, webUrl: `http://localhost:${manifest.ports.web}`, retries: 1, delayMs: 1 }).catch((error) => logger.warn(error.message));
+}
+
+async function reset(options, cwd, manifest, { logger, run }) {
+  const mode = options.resetMode ?? 'data';
+  if (mode !== 'data') {
+    throw new CliError('unsupported_reset_mode', `reset ${mode} is not implemented in the first version. Use reset data to delete only the SQLite Docker volume.`, 9);
+  }
+  if (!options.yes) {
+    throw new CliError('confirmation_required', `reset data deletes ${manifest.volumeName}. Re-run with --yes after confirming you have backed up any data you need.`, 10);
+  }
+
+  await resetDataVolume(manifest, { run });
+  await updateState(cwd, { status: 'reset', lastResetAt: new Date().toISOString() });
+  logger.success(`Deleted Docker volume ${manifest.volumeName}. .env and generated files were preserved.`);
+}

package/src/docker.js

@@ -0,0 +1,80 @@
+import { spawn } from 'node:child_process';
+import { CliError, redactSecrets } from './output.js';
+
+export async function defaultRun(command, args, { cwd = process.cwd(), stream = false } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      stdio: stream ? ['ignore', 'inherit', 'inherit'] : ['ignore', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    if (child.stdout) {
+      child.stdout.on('data', (data) => {
+        stdout += data;
+      });
+    }
+
+    if (child.stderr) {
+      child.stderr.on('data', (data) => {
+        stderr += data;
+      });
+    }
+
+    child.once('error', reject);
+    child.once('close', (code) => {
+      const result = { stdout: redactSecrets(stdout), stderr: redactSecrets(stderr), code };
+      if (code === 0) resolve(result);
+      else reject(Object.assign(new Error(result.stderr || `${command} exited with ${code}`), result));
+    });
+  });
+}
+
+export async function checkDocker({ run = defaultRun } = {}) {
+  try {
+    await run('docker', ['--version']);
+  } catch {
+    throw new CliError('missing_docker', 'Docker is required. Install Docker Desktop or Docker Engine, then re-run this command.', 4);
+  }
+  try {
+    await run('docker', ['info']);
+  } catch {
+    throw new CliError('docker_daemon_unavailable', 'Docker is installed but not running. Start Docker Desktop or Docker Engine, then re-run this command.', 5);
+  }
+  try {
+    await run('docker', ['compose', 'version']);
+  } catch {
+    throw new CliError('compose_unsupported', 'Docker Compose v2 is required. Update Docker Desktop or install the Docker Compose plugin.', 6);
+  }
+}
+
+export async function compose(manifest, args, { run = defaultRun, stream = false } = {}) {
+  return run(
+    'docker',
+    ['compose', '-p', manifest.composeProject, '--env-file', '.env', '-f', manifest.composeFile, ...args],
+    { cwd: manifest.appDir, stream }
+  );
+}
+
+export async function startCompose(manifest, options = {}) {
+  return compose(manifest, ['up', '-d'], options);
+}
+
+export async function stopCompose(manifest, options = {}) {
+  return compose(manifest, ['down'], options);
+}
+
+export async function statusCompose(manifest, options = {}) {
+  return compose(manifest, ['ps'], options);
+}
+
+export async function logsCompose(manifest, options = {}) {
+  return compose(manifest, ['logs', '--tail=100'], { ...options, stream: true });
+}
+
+export async function resetDataVolume(manifest, { run = defaultRun } = {}) {
+  await stopCompose(manifest, { run });
+  await run('docker', ['volume', 'rm', manifest.volumeName], { cwd: manifest.appDir, stream: false });
+}

package/src/health.js

@@ -0,0 +1,39 @@
+import { CliError } from './output.js';
+
+export async function waitForReady({ apiUrl, webUrl, fetch = globalThis.fetch, retries = 60, delayMs = 2000 }) {
+  let lastError = null;
+
+  for (let attempt = 1; attempt <= retries; attempt += 1) {
+    try {
+      const health = await getJson(fetch, `${apiUrl}/api/health`);
+      const onboarding = await getJson(fetch, `${apiUrl}/api/onboarding/status`);
+      await getText(fetch, webUrl);
+      return { health, onboarding, webUrl };
+    } catch (error) {
+      lastError = error;
+      if (attempt < retries) await sleep(delayMs);
+    }
+  }
+
+  throw new CliError(
+    'health_timeout',
+    `ThreadLens containers started, but readiness checks did not pass. Last error: ${lastError?.message ?? 'unknown error'}. Run npx create-threadlens-app@latest doctor or logs.`,
+    7
+  );
+}
+
+async function getJson(fetch, url) {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`${url} returned HTTP ${response.status}`);
+  return response.json();
+}
+
+async function getText(fetch, url) {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`${url} returned HTTP ${response.status}`);
+  return response.text();
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/index.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { parseArgs } from './args.js';
+import { runCommand as defaultRunCommand } from './commands.js';
+import { install as defaultInstall } from './install.js';
+import { createLogger } from './output.js';
+
+export async function main(argv = process.argv.slice(2), deps = {}) {
+  const stdout = deps.stdout ?? console.log;
+  const stderr = deps.stderr ?? console.error;
+
+  if (argv.includes('--version') || argv.includes('-v')) {
+    const { default: pkg } = await import('../package.json', { with: { type: 'json' } });
+    stdout(pkg.version);
+    return 0;
+  }
+
+  try {
+    const options = parseArgs(argv);
+    const logger = createLogger({ verbose: options.verbose, stdout, stderr });
+    if (options.command === 'install') {
+      await (deps.install ?? defaultInstall)(options, { logger });
+    } else {
+      await (deps.runCommand ?? defaultRunCommand)(options, { logger });
+    }
+    return 0;
+  } catch (error) {
+    const exitCode = Number.isInteger(error.exitCode) ? error.exitCode : 1;
+    stderr(`✕ ${error.message}`);
+    if (argv.includes('--verbose') && error.stack) stderr(error.stack);
+    return exitCode;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const code = await main();
+  process.exitCode = code;
+}

package/src/install.js

@@ -0,0 +1,96 @@
+import { mkdir, readdir, writeFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { checkDocker, defaultRun, startCompose } from './docker.js';
+import { waitForReady as defaultWaitForReady } from './health.js';
+import { createManifest, DEFAULT_THREADLENS_VERSION, updateState, writeManifestBundle } from './manifest.js';
+import { createLogger, CliError } from './output.js';
+import { assertPortAvailable, findAvailablePort } from './ports.js';
+import { renderCompose, renderEnv, renderGitignore, renderReadme } from './templates.js';
+
+export async function install(options, deps = {}) {
+  const logger = deps.logger ?? createLogger({ verbose: options.verbose });
+  const run = deps.run ?? defaultRun;
+  const waitForReady = deps.waitForReady ?? defaultWaitForReady;
+  const appDir = resolve(options.directory);
+  const instanceName = options.name ?? basename(appDir);
+
+  logger.info('ThreadLens local self-host setup\n');
+  logger.info('This will create a local ThreadLens app directory, start ThreadLens with Docker, store data in an isolated Docker volume, and open the setup wizard.');
+
+  logger.step('Checking target directory');
+  await ensureInstallDirectory(appDir);
+  logger.success(`Directory ready: ${appDir}`);
+
+  logger.step('Checking Docker prerequisites');
+  await checkDocker({ run });
+  logger.success('Docker and Compose are ready');
+
+  logger.step('Checking local ports');
+  const appPort = options.portMode === 'auto' ? await findAvailablePort(options.port) : await assertPortAvailable(options.port);
+  const apiPort = options.profile === 'dev' ? (options.apiPort ?? appPort) : appPort;
+  const webPort = options.profile === 'dev' ? (options.webPort ?? 4748) : appPort;
+  if (options.profile === 'dev') {
+    await assertPortAvailable(apiPort);
+    await assertPortAvailable(webPort);
+  }
+  logger.success(`Using app URL http://localhost:${appPort}`);
+
+  const manifest = createManifest({
+    appDir,
+    instanceName,
+    profile: options.profile,
+    appPort,
+    webPort,
+    apiPort,
+    version: DEFAULT_THREADLENS_VERSION,
+  });
+
+  logger.step('Writing generated ThreadLens files');
+  await mkdir(appDir, { recursive: true });
+  await writeFile(`${appDir}/.env`, renderEnv(manifest), { flag: 'wx', mode: 0o600 });
+  await writeFile(`${appDir}/compose.yml`, renderCompose(manifest), { flag: 'wx' });
+  await writeFile(`${appDir}/README.md`, renderReadme(manifest), { flag: 'wx' });
+  await writeFile(`${appDir}/.gitignore`, renderGitignore(), { flag: 'wx' });
+  await writeManifestBundle(appDir, manifest);
+  logger.success('Generated .env, compose.yml, README.md, .gitignore, and .threadlens metadata');
+
+  logger.step('Starting Docker Compose');
+  await startCompose(manifest, { run, stream: options.verbose });
+  await updateState(appDir, { status: 'starting', lastStartedAt: new Date().toISOString() });
+  logger.success('Docker stack started');
+
+  logger.step('Waiting for ThreadLens readiness');
+  await waitForReady({ apiUrl: `http://localhost:${apiPort}`, webUrl: `http://localhost:${webPort}` });
+  await updateState(appDir, { status: 'running', lastReadyAt: new Date().toISOString() });
+  logger.success('API, onboarding status, and web app are reachable');
+
+  const appUrl = `http://localhost:${appPort}`;
+  logger.info('\nThreadLens is running.\n');
+  logger.info(`Open: ${appUrl}\n`);
+  logger.info('Next: complete the setup wizard, choose one AI provider path, create one focused research project, add one narrow Reddit query, and run your first scout manually.');
+  logger.info('\nManagement commands: start, stop, restart, status, logs, doctor, upgrade, reset data');
+
+  if (options.open && process.stdout.isTTY && !process.env.CI) {
+    logger.info(`Open your browser to ${appUrl}`);
+  }
+
+  return { appDir, manifest, appUrl };
+}
+
+async function ensureInstallDirectory(appDir) {
+  try {
+    const entries = await readdir(appDir);
+    const allowedExisting = entries.length === 0 || entries.includes('.threadlens');
+    if (!allowedExisting) {
+      throw new CliError(
+        'directory_conflict',
+        `Refusing to overwrite non-empty directory ${appDir}. Choose another directory or run from an existing generated ThreadLens app.`,
+        8
+      );
+    }
+  } catch (error) {
+    if (error.code === 'ENOENT') return;
+    if (error instanceof CliError) throw error;
+    throw error;
+  }
+}

package/src/manifest.js

@@ -0,0 +1,94 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { CliError } from './output.js';
+import { composeProjectName, safeSlug } from './slug.js';
+
+export const MANIFEST_VERSION = 1;
+export const DEFAULT_THREADLENS_VERSION = '0.1.0';
+
+export function createManifest({ appDir, instanceName, profile, appPort, webPort, apiPort, version = DEFAULT_THREADLENS_VERSION }) {
+  const slug = safeSlug(instanceName);
+  const composeProject = composeProjectName(slug);
+  return {
+    manifestVersion: MANIFEST_VERSION,
+    createdBy: 'create-threadlens-app',
+    instanceName,
+    slug,
+    appDir: resolve(appDir),
+    profile,
+    threadlensVersion: version,
+    composeFile: 'compose.yml',
+    envFile: '.env',
+    composeProject,
+    volumeName: `${composeProject}_sqlite_data`,
+    ports: {
+      app: appPort,
+      web: webPort,
+      api: apiPort,
+    },
+  };
+}
+
+export async function writeManifestBundle(appDir, manifest) {
+  const metaDir = join(appDir, '.threadlens');
+  await mkdir(metaDir, { recursive: true });
+  await writeJson(join(metaDir, 'manifest.json'), manifest);
+  await writeJson(join(metaDir, 'state.json'), {
+    status: 'created',
+    currentVersion: manifest.threadlensVersion,
+    previousVersion: null,
+    lastStartedAt: null,
+    lastStoppedAt: null,
+    lastUpgradeAt: null,
+  });
+}
+
+export async function readManifest(appDir = process.cwd()) {
+  const manifestPath = join(appDir, '.threadlens', 'manifest.json');
+  let raw;
+  try {
+    raw = await readFile(manifestPath, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new CliError('not_threadlens_app', `This directory is not a ThreadLens app directory. Run this command from a directory containing .threadlens/manifest.json.`, 3);
+    }
+    throw new CliError('manifest_read_error', `Failed to read manifest: ${error.message}`, 3);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(raw);
+  } catch {
+    throw new CliError('manifest_corrupt', `The manifest file at ${manifestPath} is not valid JSON. The installation may be corrupted.`, 3);
+  }
+  if (manifest.manifestVersion !== MANIFEST_VERSION || manifest.createdBy !== 'create-threadlens-app') {
+    throw new CliError('manifest_incompatible', `The manifest at ${manifestPath} is not compatible with this version of create-threadlens-app.`, 3);
+  }
+  return manifest;
+}
+
+export async function readState(appDir = process.cwd()) {
+  const statePath = join(appDir, '.threadlens', 'state.json');
+  let raw;
+  try {
+    raw = await readFile(statePath, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return { status: 'unknown', currentVersion: null, previousVersion: null };
+    }
+    throw new CliError('state_read_error', `Failed to read state file: ${error.message}`, 3);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new CliError('state_corrupt', `The state file at ${statePath} is not valid JSON. The installation may be corrupted.`, 3);
+  }
+}
+
+export async function updateState(appDir, patch) {
+  const current = await readState(appDir);
+  await writeJson(join(appDir, '.threadlens', 'state.json'), { ...current, ...patch });
+}
+
+async function writeJson(path, value) {
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+}

package/src/output.js

@@ -0,0 +1,52 @@
+const SECRET_NAMES = ['ANTHROPIC_API_KEY', 'GEMINI_API_KEY', 'PARALLEL_API_KEY', 'BLUESKY_APP_PASSWORD', 'SCOUT_AI_BRIDGE_TOKEN'];
+
+export class CliError extends Error {
+  constructor(code, message, exitCode = 1) {
+    super(message);
+    this.name = 'CliError';
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}
+
+export function redactSecrets(value) {
+  let text = String(value ?? '');
+  for (const name of SECRET_NAMES) {
+    // bare: NAME=value or NAME = value (env file style)
+    text = text.replace(new RegExp(`(${name}\\s*=\\s*)([^\\n\\r]+)`, 'g'), `$1[redacted]`);
+    // YAML/colon: NAME: value
+    text = text.replace(new RegExp(`(${name}\\s*:\\s*)([^\\n\\r,}\\]]+)`, 'g'), (full, prefix, rawValue) => {
+      const normalized = String(rawValue).trim().toLowerCase();
+      if (normalized === 'set' || normalized === 'empty' || normalized === '[redacted]') {
+        return full;
+      }
+      return `${prefix}[redacted]`;
+    });
+    // JSON/quoted value: "NAME": "value" or "NAME":"value"
+    text = text.replace(new RegExp(`("${name}"\\s*:\\s*)"([^"]*)"`, 'g'), `"${name}": "[redacted]"`);
+    // standalone quoted value in any context: NAME="value" or NAME='value'
+    text = text.replace(new RegExp(`(${name}\\s*=\\s*)(['"])([^'"]+)\\2`, 'g'), `$1[redacted]`);
+  }
+  return text;
+}
+
+export function createLogger({ verbose = false, stdout = console.log, stderr = console.error } = {}) {
+  const lines = [];
+  function write(stream, line) {
+    const redacted = redactSecrets(line);
+    lines.push(redacted);
+    stream(redacted);
+  }
+  return {
+    lines,
+    verbose,
+    info: (message) => write(stdout, message),
+    step: (message) => write(stdout, `==> ${message}`),
+    success: (message) => write(stdout, `✓ ${message}`),
+    warn: (message) => write(stderr, `! ${message}`),
+    error: (message) => write(stderr, `✕ ${message}`),
+    debug: (message) => {
+      if (verbose) write(stderr, `[debug] ${message}`);
+    },
+  };
+}

package/src/ports.js

@@ -0,0 +1,35 @@
+import net from 'node:net';
+import { CliError } from './output.js';
+
+function assertValidPort(port, label = 'port') {
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new CliError('invalid_port', `${label} must be an integer between 1 and 65535 (got ${port}).`, 1);
+  }
+}
+
+export async function assertPortAvailable(port) {
+  assertValidPort(port);
+  const available = await canListen(port);
+  if (!available) {
+    throw new CliError('port_conflict', `Port ${port} is already in use. Re-run with --port auto or choose another port.`, 2);
+  }
+  return port;
+}
+
+export async function findAvailablePort(startPort) {
+  assertValidPort(startPort, 'startPort');
+  for (let port = startPort; port <= 65535; port += 1) {
+    if (await canListen(port)) return port;
+  }
+  throw new CliError('port_conflict', `No available port found at or above ${startPort}.`, 2);
+}
+
+function canListen(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', () => resolve(false));
+    server.listen(port, '127.0.0.1', () => {
+      server.close(() => resolve(true));
+    });
+  });
+}

package/src/slug.js

@@ -0,0 +1,13 @@
+export function safeSlug(value) {
+  const slug = String(value ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48);
+  return slug || 'threadlens';
+}
+
+export function composeProjectName(value) {
+  const slug = safeSlug(value);
+  return slug.startsWith('threadlens-') ? slug : `threadlens-${slug}`;
+}

package/src/templates.js

@@ -0,0 +1,139 @@
+export function renderEnv(manifest) {
+  return `# ThreadLens local self-host configuration
+# Provider keys are optional during install. You can add them here or in the setup wizard.
+THREADLENS_VERSION=${manifest.threadlensVersion}
+THREADLENS_APP_PORT=${manifest.ports.app}
+THREADLENS_WEB_PORT=${manifest.ports.web}
+THREADLENS_API_PORT=${manifest.ports.api}
+PORT=4749
+SCOUT_DB_PATH=/data/scout.db
+SCOUT_FRONTEND_DIST=/app/web/dist
+SCOUT_ONBOARDING_MODE=docker
+ANTHROPIC_API_KEY=
+GEMINI_API_KEY=
+PARALLEL_API_KEY=
+BLUESKY_HANDLE=
+BLUESKY_APP_PASSWORD=
+`;
+}
+
+export function renderCompose(manifest) {
+  if (manifest.profile === 'dev') return renderDevCompose(manifest);
+  return `name: ${manifest.composeProject}
+
+services:
+  threadlens:
+    image: ghcr.io/threadlenshq/threadlens:${'${THREADLENS_VERSION}'}
+    container_name: ${manifest.composeProject}-app
+    restart: unless-stopped
+    env_file:
+      - .env
+    environment:
+      PORT: "4749"
+      SCOUT_DB_PATH: /data/scout.db
+      SCOUT_FRONTEND_DIST: /app/web/dist
+      SCOUT_ONBOARDING_MODE: docker
+    ports:
+      - "${'${THREADLENS_APP_PORT}'}:4749"
+    volumes:
+      - sqlite_data:/data
+      - type: bind
+        source: ./.env
+        target: /data/.env
+    labels:
+      threadlens.instance: ${manifest.slug}
+      threadlens.managed-by: create-threadlens-app
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:4749/api/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+
+volumes:
+  sqlite_data:
+    name: ${manifest.volumeName}
+`;
+}
+
+function renderDevCompose(manifest) {
+  return `name: ${manifest.composeProject}
+
+services:
+  api:
+    image: ghcr.io/threadlenshq/threadlens-api-dev:${'${THREADLENS_VERSION}'}
+    container_name: ${manifest.composeProject}-api
+    env_file:
+      - .env
+    environment:
+      PORT: "4749"
+      SCOUT_DB_PATH: /data/scout.db
+      SCOUT_ONBOARDING_MODE: docker
+    ports:
+      - "${'${THREADLENS_API_PORT}'}:4749"
+    volumes:
+      - sqlite_data:/data
+      - type: bind
+        source: ./.env
+        target: /data/.env
+    labels:
+      threadlens.instance: ${manifest.slug}
+      threadlens.managed-by: create-threadlens-app
+  web:
+    image: ghcr.io/threadlenshq/threadlens-web-dev:${'${THREADLENS_VERSION}'}
+    container_name: ${manifest.composeProject}-web
+    environment:
+      VITE_API_PROXY_TARGET: http://api:4749
+    ports:
+      - "${'${THREADLENS_WEB_PORT}'}:4748"
+    depends_on:
+      - api
+    labels:
+      threadlens.instance: ${manifest.slug}
+      threadlens.managed-by: create-threadlens-app
+
+volumes:
+  sqlite_data:
+    name: ${manifest.volumeName}
+`;
+}
+
+export function renderReadme(manifest) {
+  const appUrl = `http://localhost:${manifest.ports.app}`;
+  return `# ${manifest.instanceName}
+
+This directory was generated by \`create-threadlens-app\`. ThreadLens runs locally with Docker Compose and stores SQLite data in the Docker volume \`${manifest.volumeName}\`.
+
+Open: ${appUrl}
+
+## Commands
+
+\`\`\`bash
+npx create-threadlens-app@latest start
+npx create-threadlens-app@latest stop
+npx create-threadlens-app@latest restart
+npx create-threadlens-app@latest status
+npx create-threadlens-app@latest logs
+npx create-threadlens-app@latest doctor
+npx create-threadlens-app@latest upgrade
+npx create-threadlens-app@latest reset data
+\`\`\`
+
+## Files
+
+- \`.env\` contains local runtime settings and provider keys. Do not commit it.
+- \`compose.yml\` is the exact Docker Compose file used by this instance.
+- \`.threadlens/manifest.json\` records ports, Compose project names, and volume names.
+
+## First run
+
+Open ${appUrl}, complete the setup wizard, choose one AI provider path, create one focused research project, add one narrow Reddit query, and run your first scout manually.
+
+## Reset warning
+
+\`npx create-threadlens-app@latest reset data\` deletes the Docker SQLite volume for this instance. It does not delete \`.env\` or this app directory.
+`;
+}
+
+export function renderGitignore() {
+  return `.env\n.threadlens/diagnostics/\n`;
+}