@nuucognition/flint-cli 0.1.0-beta.0

package/README.md

@@ -0,0 +1,344 @@
+
+# Flint CLI
+
+Command-line interface for managing Flint cognitive workspaces.
+
+Flint extends Mesh with shards, git integration, and structured modules for AI-assisted workflows.
+
+## Installation
+
+```bash
+# Install via the internal Flint install script.
+# For local development in this monorepo:
+pnpm install
+pnpm --filter @nuucognition/flint-cli dev
+```
+
+## Commands
+
+### `flint init <name>`
+
+Create a new flint workspace.
+
+```bash
+flint init my-project
+flint init my-project --path ~/workspaces
+flint init my-project --preset default
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `-p, --path <dir>` | Parent directory |
+| `--preset <name>` | Use a preset (e.g., "default") |
+
+**Creates:**
+```
+(Flint) my-project/
+├── .flint/
+│   └── flint.lock
+├── flint.toml
+├── Imports/
+├── Exports/
+├── Workspace/
+├── Shards/
+├── Media/
+└── Mesh/
+```
+
+`flint init` creates the minimal structure and then runs `flint sync` to clone `.obsidian` and install any preset shards/mods.
+
+### `flint list`
+
+List all registered flints.
+
+```bash
+flint list
+flint list --json
+flint list --full-path
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--json` | Output as JSON |
+| `--full-path` | Show full paths |
+| `-s, --status` | Show valid/broken status |
+| `--sub` | Include subflints (dev mode only) |
+
+**Aliases:** `flint ls`
+
+### `flint index`
+
+Index all markdown files (same as `mesh index`).
+
+```bash
+flint index
+flint index --dry-run
+flint index --verbose
+```
+
+### `flint sync`
+
+Sync flint.toml with installed shards/mods, workspace references, imports, and `.obsidian`.
+
+```bash
+flint sync
+flint sync --path /path/to/(Flint) my-project
+```
+
+### `flint shard`
+
+Manage shards.
+
+#### `flint shard list`
+
+List installed or available shards.
+
+```bash
+flint shard list              # List installed shards
+flint shard list --available  # List all available shards
+```
+
+#### `flint shard install <shorthand>`
+
+Install a shard.
+
+```bash
+flint shard install ld        # Living Documents
+flint shard install inc       # Increments (depends on ld)
+flint shard install ma        # Mesh Agent (depends on ld)
+flint shard install cc        # Claude Code (depends on ma)
+flint shard install cc --force  # Overwrite existing files
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `-p, --path <dir>` | Path to flint (default: auto-detect) |
+| `-f, --force` | Overwrite existing files for integration shards |
+
+**Available Shards:**
+
+| Shorthand | Name | Type | Depends |
+|-----------|------|------|---------|
+| `ld` | Living Document | prompt | - |
+| `inc` | Increments | prompt | ld |
+| `ma` | Mesh Agent | prompt | ld |
+| `cc` | Claude Code | integration | ma |
+
+### `flint mod`
+
+Manage mods (environment modifications).
+
+```bash
+flint mod list
+flint mod list --available
+flint mod install git
+```
+
+### `flint open`
+
+Open a flint in configured applications.
+
+```bash
+flint open                    # Open current flint
+flint open my-project         # Open by name from registry
+```
+
+**Dev-only:** enable with `flint mode dev` or `flint --dev open ...`.
+
+**Behavior:**
+- Opens the flint in all apps configured in `~/.flint/config.toml`
+- Default (no config): opens in Obsidian only
+- Supports: obsidian, cursor, vscode, or any custom app
+
+**Configure with:**
+```bash
+flint config set open.apps '["obsidian", "cursor"]'
+```
+
+### `flint config`
+
+Manage global Flint configuration stored at `~/.flint/config.toml`.
+
+```bash
+flint config                           # View all config
+flint config get open.apps             # Get specific value
+flint config set open.apps '["obsidian", "cursor"]'  # Set value
+```
+
+**Available Settings:**
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `mode` | string | build default | Feature mode (use `flint mode` to manage) |
+| `open.apps` | string[] | `["obsidian"]` | Apps to open flints in |
+
+### `flint mode`
+
+Manage feature tiers (production, experimental, dev). This setting is persisted in `~/.flint/config.toml`.
+
+```bash
+flint mode
+flint mode experimental
+flint mode --list
+```
+
+Use `--experimental` or `--dev` on a single command to override the current mode.
+Dev-only commands include `open` and `upgrade`.
+
+### `flint git`
+
+Git operations with flint awareness.
+
+#### `flint git init`
+
+Initialize git repository with managed `.gitignore`.
+
+```bash
+flint git init
+```
+
+#### `flint git sync`
+
+Update `.gitignore` with workspace entries.
+
+```bash
+flint git sync
+```
+
+#### `flint git <command>`
+
+Passthrough to git.
+
+```bash
+flint git status
+flint git add .
+flint git commit -m "message"
+```
+
+### `flint export`
+
+Manage exports defined in `Exports/`.
+
+```bash
+flint export list
+flint export build
+flint export build <name>
+```
+
+### `flint import`
+
+Manage imports from other registered flints.
+
+```bash
+flint import list
+flint import add "NUU Flint/Guide"
+flint import remove "NUU Flint/Guide"
+```
+
+## Configuration
+
+### flint.toml
+
+Located at the flint root:
+
+```toml
+[flint]
+name = "My Project"
+type = "flint"
+
+[shards]
+required = ["core"]
+
+[mods]
+required = ["git"]
+```
+
+Optional sections include `[imports]` and `[workspace]` declarations.
+
+### flint.lock
+
+Stored at `.flint/flint.lock` and tracks the current Flint version plus installed shards/mods.
+
+### Shard Manifest (shard.yaml)
+
+Shards are defined by `shard.yaml`:
+
+```yaml
+version: 1
+name: 'My Shard'
+shorthand: 'ms'
+description: 'What this shard does'
+depends:
+  - ld                  # Optional dependencies
+```
+
+**Integration shards** can also specify setup:
+
+```yaml
+setup:
+  directories:
+    - path: '.my-tool'
+  files:
+    - path: 'CONFIG.md'
+      template: 'templates/config.md.tmpl'
+  state:
+    installed: true
+    version: '1.0.0'
+```
+
+## Shard Types
+
+### Prompt Shards
+
+Markdown files that provide context and skills for AI agents.
+
+- Installed to `Shards/<Name>/`
+- Read by agents for context
+- No runtime execution
+
+### Integration Shards
+
+Create files outside the `Shards/` directory.
+
+- Can create directories and files anywhere in the flint
+- Use templates with variable substitution
+- Store state in `Shards/<Name>/.installed.json`
+
+**Template Variables:**
+
+| Variable | Value |
+|----------|-------|
+| `{{uuid}}` | Random UUID |
+| `{{date}}` | Current date (YYYY-MM-DD) |
+
+## Programmatic Usage
+
+```typescript
+import {
+  createFlint,
+  findFlintRoot,
+  installShard,
+  listAvailableShards,
+  initGit,
+} from '@nuucognition/flint';
+
+// Create a new flint
+const entry = await createFlint({
+  name: 'my-project',
+});
+
+// Install a shard
+await installShard(entry.path, 'ld');
+
+// List available shards
+const shards = await listAvailableShards();
+
+// Initialize git in the current flint (if detected)
+const flintPath = await findFlintRoot(process.cwd());
+if (flintPath) {
+  await initGit(flintPath);
+}
+```

package/bin/flint-prod.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+await import(join(__dirname, '..', 'dist', 'index.js'));

package/bin/flint.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const srcEntry = join(__dirname, '..', 'src', 'index.ts');
+
+// Find tsx in node_modules (works in monorepo)
+const tsxPath = join(__dirname, '..', 'node_modules', '.bin', 'tsx');
+
+// Set dev mode for local development (running from source)
+const result = spawnSync(tsxPath, [srcEntry, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  env: { ...process.env, FLINT_MODE: 'dev' },
+});
+
+process.exit(result.status ?? 0);