create-lore 0.8.0 → 0.9.0

package/.gitattributes

@@ -0,0 +1,2 @@
+# Force LF line endings everywhere — prevents CRLF issues on Windows.
+* text=auto eol=lf

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,24 @@
+---
+name: Bug report
+about: Something isn't working as expected
+labels: bug
+---
+
+**What happened?**
+
+A clear description of the bug.
+
+**Steps to reproduce**
+
+1. ...
+2. ...
+
+**Expected behavior**
+
+What should have happened instead.
+
+**Environment**
+
+- OS:
+- Node version:
+- create-lore version:

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an improvement or new capability
+labels: enhancement
+---
+
+**What problem does this solve?**
+
+Describe the use case or pain point.
+
+**Proposed solution**
+
+How you'd like it to work.
+
+**Alternatives considered**
+
+Any workarounds or other approaches you've tried.

package/.github/workflows/release.yml

@@ -0,0 +1,75 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: write
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node-version: [18, 20]
+    steps:
+      - uses: actions/checkout@v4  # checkout create-lore (this repo)
+      - uses: actions/checkout@v4  # checkout lore template at matching tag
+        with:
+          repository: lorehq/lore
+          ref: ${{ github.ref_name }}
+          path: lore
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm test
+        env:
+          LORE_TEMPLATE: ${{ github.workspace }}/lore
+
+  verify-tag:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Verify tag matches package.json version
+        run: |
+          tag="${GITHUB_REF#refs/tags/v}"
+          pkg="$(node -p "require('./package.json').version")"
+          if [[ "$tag" != "$pkg" ]]; then
+            echo "::error::Tag v$tag does not match package.json version $pkg"
+            exit 1
+          fi
+          echo "Tag v$tag matches package.json"
+      - name: Verify matching lore tag exists
+        run: |
+          tag="${GITHUB_REF#refs/tags/}"
+          if ! git ls-remote --tags https://github.com/lorehq/lore.git "refs/tags/$tag" | grep -q "$tag"; then
+            echo "::error::lorehq/lore does not have tag $tag — tag lore first"
+            exit 1
+          fi
+          echo "lorehq/lore has matching tag $tag"
+
+  publish:
+    needs: [test, verify-tag]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+      - name: Publish to npm
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          tag="${GITHUB_REF#refs/tags/}"
+          gh release delete "$tag" --yes 2>/dev/null || true
+          gh release create "$tag" \
+            --title "$tag" \
+            --generate-notes

package/.github/workflows/test.yml

@@ -0,0 +1,52 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node-version: [18, 20]
+    steps:
+      - uses: actions/checkout@v4  # checkout create-lore (this repo)
+      - uses: actions/checkout@v4  # checkout lore template (used as LORE_TEMPLATE)
+        with:
+          repository: lorehq/lore
+          path: lore
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm test
+        env:
+          LORE_TEMPLATE: ${{ github.workspace }}/lore
+
+  e2e:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          repository: lorehq/lore
+          path: lore
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Scaffold a project and validate it
+        shell: bash
+        env:
+          LORE_TEMPLATE: ${{ github.workspace }}/lore
+        run: |
+          node bin/create-lore.js test-project
+          cd test-project
+          bash scripts/validate-consistency.sh

package/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing to create-lore
+
+Thanks for your interest in contributing. `create-lore` is the CLI scaffolder for [Lore](https://github.com/lorehq/lore).
+
+## Dev Setup
+
+```bash
+git clone https://github.com/lorehq/create-lore.git
+cd create-lore
+```
+
+Requires **Node.js 18+**. Zero runtime dependencies.
+
+## Running Tests
+
+```bash
+npm test
+```
+
+Tests use `LORE_TEMPLATE` env var to point at a local lore repo instead of cloning from GitHub:
+
+```bash
+LORE_TEMPLATE=../lore npm test
+```
+
+## Pull Requests
+
+1. Fork the repo and create a branch from `main`
+2. Make your changes
+3. Run `npm test`
+4. Open a pull request
+
+## What We're Looking For
+
+- Bug fixes with clear reproduction steps
+- Better error messaging for common failure modes
+- Test coverage improvements
+
+## Guidelines
+
+- Keep changes focused — one concern per PR
+- Match existing code style
+- For framework changes (hooks, skills, lib), contribute to [lorehq/lore](https://github.com/lorehq/lore) instead
+
+## Reporting Issues
+
+Use [GitHub Issues](../../issues). For security vulnerabilities, see [SECURITY.md](SECURITY.md).
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the Apache-2.0 license.

package/README.md

@@ -1,37 +1,57 @@
 # create-lore
 
-Create a new [Lore](https://github.com/lorehq/lore) knowledge-persistent AI coding framework repo.
+Bootstrap a new [Lore](https://github.com/lorehq/lore) project — persistent memory for AI coding agents.
 
-## Usage
+## The Problem
+
+AI coding agents (Claude Code, Cursor, OpenCode) forget everything between sessions. Every session you re-explain project structure, re-discover API quirks, and repeat lessons learned yesterday. Lore fixes that.
+
+## What Lore Does
+
+Lore wraps your coding agent in a git-versioned knowledge base. Hooks fire automatically to reinforce knowledge capture as you work. Gotchas become skills, and every future session starts with what previous sessions learned. Complex work delegates to focused workers loaded with curated skills.
+
+- **Skills** — API quirks, auth gotchas, encoding tricks. Captured once, loaded forever.
+- **Knowledge docs** — Environment details, runbooks, architecture decisions. Accumulated across sessions.
+- **Work tracking** — Roadmaps, plans, and brainstorms that persist and appear in every session banner.
+- **Hooks** — Session init, capture reminders, memory protection. All automatic.
+
+## Quick Start
 
 ```bash
-npx create-lore myproject
+npx create-lore my-project
+cd my-project
+git add -A && git commit -m "Init Lore"
 ```
 
-This creates `lore-myproject/` with the full Lore framework — hooks, skills, scripts, and operating instructions that teach Claude Code to learn and remember across sessions.
+Then open the project in your agent. Hooks fire automatically.
 
-## What you get
+## Supported Platforms
 
-- **AGENTS.md / CLAUDE.md** — Operating instructions Claude Code reads automatically
-- **Hooks** — Session init, memory guard, post-action capture reminders
-- **Skills** — `create-skill` and `create-agent` for building your knowledge base
-- **Scripts** — Registry generation, agent generation, consistency validation
+| Platform | Integration |
+|----------|-------------|
+| Claude Code | `hooks/` + `CLAUDE.md` |
+| Cursor | `.cursor/hooks/` + `.cursor/mcp/` + `.cursor/rules/` |
+| OpenCode | `.opencode/plugins/` + `opencode.json` |
+
+All platforms share the same knowledge base. No configuration needed.
 
 ## Options
 
 ```bash
-npx create-lore myproject       # creates ./lore-myproject/
-npx create-lore ./custom-path   # creates at specific path
+npx create-lore my-project       # creates ./my-project/
+npx create-lore ./custom-path    # creates at specific path
+npx create-lore --help           # show usage
+npx create-lore --version        # show version
 ```
 
-## After setup
+## Requirements
 
-```bash
-cd lore-myproject
-git add -A && git commit -m "Init Lore"
-```
+- Node.js 18+
+- git
+
+## Docs
 
-Then open Claude Code in the project. The hooks will fire automatically and the self-learning loop begins.
+Full documentation: [lorehq.github.io/lore-docs](https://lorehq.github.io/lore-docs/)
 
 ## License
 

package/SECURITY.md

@@ -0,0 +1,24 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly:
+
+1. **Do not** open a public GitHub issue
+2. Email the maintainers or use [GitHub's private vulnerability reporting](../../security/advisories/new)
+3. Include steps to reproduce and potential impact
+
+We will acknowledge receipt within 48 hours and provide a timeline for a fix.
+
+## Scope
+
+`create-lore` is a CLI scaffolder that clones a template repo and initializes a new project. Security concerns are primarily:
+
+- Shell command execution during project scaffolding (`git clone`, `git init`)
+- Template integrity (clones from a pinned version tag on GitHub)
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.8.x   | Yes       |

package/bin/create-lore.js

@@ -18,9 +18,25 @@ const fs = require('fs');
 const path = require('path');
 
 const REPO_URL = 'https://github.com/lorehq/lore.git';
+const pkg = require('../package.json');
 
 // -- Parse arguments --
-const name = process.argv[2];
+const arg = process.argv[2];
+if (arg === '--help' || arg === '-h') {
+  console.log(`create-lore v${pkg.version}\n`);
+  console.log('Usage: create-lore <name|path>\n');
+  console.log('Bootstrap a new Lore knowledge-persistent agent repo.\n');
+  console.log('Examples:');
+  console.log('  npx create-lore myproject       # creates ./myproject/');
+  console.log('  npx create-lore ./custom-path   # creates at specific path');
+  process.exit(0);
+}
+if (arg === '--version' || arg === '-v') {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const name = arg;
 if (!name) {
   console.error('Usage: create-lore <name>');
   process.exit(1);
@@ -31,6 +47,25 @@ if (!name) {
 const isPath = name.includes('/') || name.includes(path.sep);
 const targetDir = path.resolve(isPath ? name : `./${name}`);
 
+// Validate every segment of the resolved path's tail (the parts the user controls).
+// For simple names, validate the name directly. For paths, validate the basename.
+// This prevents shell-hostile characters like ; | & $ ` from sneaking through.
+const segmentPattern = /^[a-zA-Z0-9._-]+$/;
+const finalName = path.basename(targetDir);
+if (!segmentPattern.test(finalName)) {
+  console.error(`Error: Invalid project name '${finalName}'`);
+  console.error('Names may contain letters, numbers, dots, hyphens, and underscores.');
+  process.exit(1);
+}
+
+// Guard against path traversal — resolved target must be under cwd
+const cwd = process.cwd();
+if (!targetDir.startsWith(cwd + path.sep) && targetDir !== cwd) {
+  console.error(`Error: Target directory '${targetDir}' is outside the current working directory.`);
+  console.error('Use a relative name or path within the current directory.');
+  process.exit(1);
+}
+
 if (fs.existsSync(targetDir)) {
   console.error(`Error: ${targetDir} already exists`);
   process.exit(1);
@@ -45,7 +80,23 @@ try {
   if (templateDir) {
     fs.cpSync(templateDir, tmpDir, { recursive: true });
   } else {
-    execSync(`git clone --depth 1 ${REPO_URL} "${tmpDir}"`, { stdio: 'pipe' });
+    try {
+      execSync(`git clone --depth 1 --branch v${pkg.version} ${REPO_URL} "${tmpDir}"`, { stdio: 'pipe' });
+    } catch (err) {
+      const stderr = err.stderr ? err.stderr.toString() : '';
+      if (stderr.includes('not found') || stderr.includes('not a valid')) {
+        console.error(`Error: Version tag v${pkg.version} not found in ${REPO_URL}`);
+        console.error('This usually means the release tag is missing. Try:');
+        console.error('  npx create-lore@latest ' + name);
+      } else if (stderr.includes('Could not resolve host') || stderr.includes('unable to access')) {
+        console.error('Error: Cannot reach github.com');
+        console.error('Check your internet connection, DNS, and firewall/proxy settings.');
+      } else {
+        console.error('Error: Failed to clone template from GitHub');
+        console.error(stderr.trim() || err.message);
+      }
+      process.exit(1);
+    }
   }
   fs.rmSync(path.join(tmpDir, '.git'), { recursive: true, force: true });
   fs.cpSync(tmpDir, targetDir, { recursive: true });
@@ -57,7 +108,12 @@ try {
 // -- Write .lore-config --
 const projectName = isPath ? path.basename(targetDir) : name;
 // Read version from the template's .lore-config so instances track their source version
-const templateConfig = JSON.parse(fs.readFileSync(path.join(targetDir, '.lore-config'), 'utf8'));
+let templateConfig;
+try {
+  templateConfig = JSON.parse(fs.readFileSync(path.join(targetDir, '.lore-config'), 'utf8'));
+} catch (e) {
+  templateConfig = {};
+}
 const config = {
   name: projectName,
   version: templateConfig.version || '0.0.0',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-lore",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Create a new Lore knowledge-persistent agent repo",
   "bin": {
     "create-lore": "bin/create-lore.js"
@@ -8,7 +8,12 @@
   "scripts": {
     "test": "node --test test/create-lore.test.js"
   },
-  "keywords": ["lore", "agent", "ai", "knowledge"],
+  "keywords": [
+    "lore",
+    "agent",
+    "ai",
+    "knowledge"
+  ],
   "license": "Apache-2.0",
   "engines": {
     "node": ">=18"

package/test/create-lore.test.js

@@ -9,7 +9,7 @@ const fs = require('fs');
 const path = require('path');
 
 const BIN = path.resolve(__dirname, '../bin/create-lore.js');
-const TEMPLATE = path.resolve(__dirname, '../../lore'); // Sibling lore repo
+const TEMPLATE = process.env.LORE_TEMPLATE || path.resolve(__dirname, '../../lore');
 const OUTPUT = path.resolve(__dirname, '../test-output');
 
 // Run the installer with LORE_TEMPLATE pointing at the local template
@@ -21,6 +21,15 @@ function run(args = '') {
   });
 }
 
+// Run with exact argv (no shell interpretation) — for testing shell metacharacters
+function runExact(name) {
+  return require('child_process').execFileSync('node', [BIN, name], {
+    env: { ...process.env, LORE_TEMPLATE: TEMPLATE },
+    stdio: 'pipe',
+    encoding: 'utf8',
+  });
+}
+
 function cleanup() {
   if (fs.existsSync(OUTPUT)) fs.rmSync(OUTPUT, { recursive: true });
 }
@@ -29,6 +38,18 @@ describe('create-lore', () => {
   before(cleanup);
   after(cleanup);
 
+  it('--help shows usage text', () => {
+    const output = run('--help');
+    assert.ok(output.includes('Usage:'), 'shows usage');
+    assert.ok(output.includes('create-lore'), 'mentions create-lore');
+  });
+
+  it('--version outputs package.json version', () => {
+    const output = run('--version');
+    const pkg = require('../package.json');
+    assert.equal(output.trim(), pkg.version);
+  });
+
   it('exits with error when no name given', () => {
     assert.throws(() => run(''), { status: 1 });
   });
@@ -55,6 +76,17 @@ describe('create-lore', () => {
     fs.rmSync(OUTPUT, { recursive: true });
   });
 
+  it('rejects names with shell metacharacters', () => {
+    assert.throws(() => runExact('foo;echo pwned'), /Invalid project name/);
+    assert.throws(() => runExact('foo$(cmd)'), /Invalid project name/);
+    assert.throws(() => runExact('foo|bar'), /Invalid project name/);
+  });
+
+  it('rejects path arguments with shell metacharacters in basename', () => {
+    assert.throws(() => runExact('./foo;rm'), /Invalid project name/);
+    assert.throws(() => runExact('/tmp/bad$(cmd)'), /Invalid project name/);
+  });
+
   // -- Template content tests --
   // These skip gracefully if the template hasn't reached that phase yet.