sidecar-cli 0.1.3 → 0.1.4-rc.1

package/README.md

@@ -85,12 +85,41 @@ npm run dev -- --help
 
 ## Quick start
 
-Initialize in a project directory:
+1. Initialize in a project directory:
 
 ```bash
 sidecar init
 ```
 
+2. (Optional) Define shared instruction templates once:
+
+```bash
+mkdir -p ~/.sidecar-cli/instructions
+```
+
+Create template files such as:
+
+- `~/.sidecar-cli/instructions/web-app.md`
+- `~/.sidecar-cli/instructions/desktop-app.md`
+
+3. Initialize with a shared template (writes project `instructions.md`):
+
+```bash
+sidecar init --instructions-template web-app
+```
+
+Or load directly from a specific file:
+
+```bash
+sidecar init --instructions-file /absolute/path/to/instructions.md
+```
+
+Notes:
+
+- `--instructions-template <name>` resolves to `~/.sidecar-cli/instructions/<name>.md`.
+- Use either `--instructions-template` or `--instructions-file` (not both).
+- If `instructions.md` already exists, Sidecar will not overwrite it unless `--force` is used.
+
 This creates:
 
 - `.sidecar/sidecar.db`
@@ -100,6 +129,7 @@ This creates:
 - `.sidecar/summary.md`
 - `AGENTS.md` (repo root)
 - `CLAUDE.md` (repo root)
+- `instructions.md` (repo root, only when `--instructions-template` or `--instructions-file` is provided)
 
 Use `--force` to overwrite Sidecar-managed files.
 
@@ -107,7 +137,7 @@ Use `--force` to overwrite Sidecar-managed files.
 
 Global:
 
-- `sidecar init [--force] [--name <project-name>] [--json]`
+- `sidecar init [--force] [--name <project-name>] [--instructions-template <name>] [--instructions-file <path>] [--json]`
 - `sidecar status [--json]`
 - `sidecar preferences show [--json]`
 - `sidecar ui [--no-open] [--port <port>] [--install-only] [--project <path>] [--reinstall]`

package/dist/cli.js

@@ -9,6 +9,7 @@ import { initializeSchema } from './db/schema.js';
 import { findSidecarRoot, getSidecarPaths } from './lib/paths.js';
 import { nowIso, humanTime, stringifyJson } from './lib/format.js';
 import { SidecarError } from './lib/errors.js';
+import { GLOBAL_INSTRUCTIONS_DIR, resolveInstructionsSource } from './lib/instructions.js';
 import { jsonFailure, jsonSuccess, printJsonEnvelope } from './lib/output.js';
 import { bannerDisabled, renderBanner } from './lib/banner.js';
 import { getUpdateNotice } from './lib/update-check.js';
@@ -279,14 +280,21 @@ program
     .description('Initialize Sidecar in the current directory')
     .option('--force', 'Overwrite Sidecar files if they already exist')
     .option('--name <project-name>', 'Project name (defaults to current directory name)')
+    .option('--instructions-template <name>', `Load instructions template by name from ${GLOBAL_INSTRUCTIONS_DIR} (example: "web-app")`)
+    .option('--instructions-file <path>', 'Load instructions from a specific markdown file path')
     .option('--json', 'Print machine-readable JSON output')
-    .addHelpText('after', '\nExamples:\n  $ sidecar init\n  $ sidecar init --name "My Project"\n  $ sidecar init --force --json')
+    .addHelpText('after', '\nExamples:\n  $ sidecar init\n  $ sidecar init --name "My Project"\n  $ sidecar init --instructions-template web-app\n  $ sidecar init --instructions-file ~/.sidecar-cli/instructions/desktop.md\n  $ sidecar init --force --json')
     .action((opts) => {
     const command = 'init';
     try {
         const rootPath = process.cwd();
         const sidecar = getSidecarPaths(rootPath);
         const projectName = opts.name?.trim() || path.basename(rootPath);
+        const resolvedInstructions = resolveInstructionsSource({
+            templateName: opts.instructionsTemplate,
+            sourcePath: opts.instructionsFile,
+            cwd: rootPath,
+        });
         if (fs.existsSync(sidecar.sidecarPath)) {
             const stat = fs.lstatSync(sidecar.sidecarPath);
             if (stat.isSymbolicLink()) {
@@ -315,6 +323,13 @@ program
             files.push(sidecar.rootAgentsPath);
         if (shouldWriteRootClaude)
             files.push(sidecar.rootClaudePath);
+        if (resolvedInstructions) {
+            const canWriteInstructions = Boolean(opts.force) || !fs.existsSync(sidecar.rootInstructionsPath);
+            if (!canWriteInstructions) {
+                fail(`Refusing to overwrite ${sidecar.rootInstructionsPath}. Re-run with --force or choose another destination.`);
+            }
+            files.push(sidecar.rootInstructionsPath);
+        }
         fs.mkdirSync(sidecar.sidecarPath, { recursive: true });
         if (opts.force) {
             for (const file of [
@@ -365,6 +380,9 @@ program
         if (shouldWriteRootClaude) {
             fs.writeFileSync(sidecar.rootClaudePath, renderClaudeMarkdown(projectName));
         }
+        if (resolvedInstructions) {
+            fs.writeFileSync(sidecar.rootInstructionsPath, resolvedInstructions.content);
+        }
         const db2 = new DatabaseSync(sidecar.dbPath);
         const refreshed = refreshSummaryFile(db2, rootPath, 1, 10);
         db2.close();
@@ -374,6 +392,7 @@ program
             projectName,
             filesCreated: files,
             summaryGeneratedAt: refreshed.generatedAt,
+            instructionsSource: resolvedInstructions?.sourceLabel ?? null,
             timestamp: nowIso(),
         };
         const shouldShowBanner = !opts.json && !bannerDisabled();
@@ -386,6 +405,7 @@ program
             'Sidecar provides local project memory for decisions, work logs, tasks, and summaries.',
             'Created:',
             ...data.filesCreated.map((f) => `- ${f}`),
+            ...(resolvedInstructions ? ['', `Loaded instructions.md from ${resolvedInstructions.sourceLabel}`] : []),
             '',
             'Next step:',
             'sidecar context',

package/dist/lib/instructions.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { SidecarError } from './errors.js';
+export const GLOBAL_INSTRUCTIONS_DIR = path.join(os.homedir(), '.sidecar-cli', 'instructions');
+function readInstructionsFile(sourcePath, sourceLabel) {
+    if (!fs.existsSync(sourcePath)) {
+        throw new SidecarError(`Instructions source not found: ${sourcePath}`);
+    }
+    const stat = fs.statSync(sourcePath);
+    if (!stat.isFile()) {
+        throw new SidecarError(`Instructions source is not a file: ${sourcePath}`);
+    }
+    return {
+        sourcePath,
+        sourceLabel,
+        content: fs.readFileSync(sourcePath, 'utf8'),
+    };
+}
+export function resolveInstructionsSource(opts) {
+    const templateName = opts.templateName?.trim();
+    const sourcePath = opts.sourcePath?.trim();
+    if (!templateName && !sourcePath)
+        return null;
+    if (templateName && sourcePath) {
+        throw new SidecarError('Use only one option: --instructions-template or --instructions-file.');
+    }
+    if (sourcePath) {
+        const resolvedPath = path.resolve(opts.cwd, sourcePath);
+        return readInstructionsFile(resolvedPath, `file:${resolvedPath}`);
+    }
+    const fileName = templateName?.endsWith('.md') ? templateName : `${templateName}.md`;
+    if (!fileName)
+        return null;
+    const globalPath = path.join(GLOBAL_INSTRUCTIONS_DIR, fileName);
+    if (!fs.existsSync(globalPath)) {
+        throw new SidecarError(`Instructions template "${templateName}" not found at ${globalPath}. Create it under ${GLOBAL_INSTRUCTIONS_DIR}.`);
+    }
+    return readInstructionsFile(globalPath, `template:${templateName}`);
+}

package/dist/lib/paths.js

@@ -11,6 +11,7 @@ export function getSidecarPaths(rootPath) {
         promptsPath: path.join(sidecarPath, 'prompts'),
         rootAgentsPath: path.join(rootPath, 'AGENTS.md'),
         rootClaudePath: path.join(rootPath, 'CLAUDE.md'),
+        rootInstructionsPath: path.join(rootPath, 'instructions.md'),
         dbPath: path.join(sidecarPath, 'sidecar.db'),
         configPath: path.join(sidecarPath, 'config.json'),
         preferencesPath: path.join(sidecarPath, 'preferences.json'),

package/dist/services/capabilities-service.js

@@ -22,7 +22,7 @@ export function getCapabilitiesManifest(version) {
                 description: 'Initialize Sidecar in the current directory',
                 json_output: true,
                 arguments: [],
-                options: ['--force', '--name <project-name>', '--json'],
+                options: ['--force', '--name <project-name>', '--instructions-template <name>', '--instructions-file <path>', '--json'],
             },
             {
                 name: 'status',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidecar-cli",
-  "version": "0.1.3",
+  "version": "0.1.4-rc.1",
   "description": "Local-first project memory and recording tool",
   "scripts": {
     "build": "npm run clean && tsc -p tsconfig.json",