cineprompt 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Light Owl, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# cineprompt
+
+CLI tool for building structured AI video prompts and share links via [cineprompt.io](https://cineprompt.io).
+
+Turn shot descriptions into optimized prompts for Sora, Runway, Kling, Veo, Seedance, and other AI video generators.
+
+## Install
+
+```bash
+npm install -g cineprompt
+```
+
+Or run directly:
+
+```bash
+npx cineprompt --help
+```
+
+## Setup
+
+Get your API key from [cineprompt.io](https://cineprompt.io) → Settings → API Access (Pro subscription required).
+
+```bash
+cineprompt auth cp_your_api_key_here
+```
+
+## Usage
+
+### Build a share link from state JSON
+
+```bash
+cineprompt build '{"mode":"single","complexity":"complex","subjectType":"landscape","fields":{"media_type":["cinematic"],"tone":["peaceful"],"env_time":"golden hour, warm late afternoon light","shot_type":"establishing shot","movement":"pull out","focal_length":"24mm lens","dof":"deep focus","color_grade":"warm tones"}}'
+```
+
+Output:
+
+```
+🎬 https://cineprompt.io/p/a8k2mf
+```
+
+### Build from a JSON file
+
+```bash
+cineprompt build --file shot.json
+```
+
+### Build from stdin
+
+```bash
+cat shot.json | cineprompt build
+```
+
+### Browse available fields
+
+```bash
+# List all 92 fields
+cineprompt fields
+
+# Show valid values for a specific field
+cineprompt fields env_time
+cineprompt fields shot_type
+cineprompt fields media_type
+```
+
+## State JSON format
+
+```json
+{
+  "mode": "single",
+  "complexity": "simple",
+  "subjectType": "character",
+  "fields": {
+    "media_type": ["cinematic"],
+    "tone": ["moody"],
+    "char_label": "A weathered fisherman",
+    "subject_description": "Deep wrinkles, sun-damaged skin",
+    "setting": "exterior",
+    "location_type": "dock, pier",
+    "env_time": "dawn, first light",
+    "weather": "fog",
+    "shot_type": "close-up",
+    "movement": "handheld",
+    "dof": "shallow depth of field, bokeh",
+    "lighting_style": "soft light",
+    "color_grade": "desaturated",
+    "sfx_environment": ["waves crashing, water ambience"]
+  }
+}
+```
+
+### Required fields
+
+- **mode** — `"single"` (multishot and frame-to-motion coming soon)
+- **fields** — object mapping field names to values
+
+### Optional fields
+
+- **complexity** — `"simple"` (default) or `"complex"` (unlocks camera body, lens brand, film stock, color science)
+- **subjectType** — `"character"`, `"object"`, `"vehicle"`, `"creature"`, `"landscape"`, or `"abstract"`
+
+### Field types
+
+- **Button fields** accept exact string values (use `cineprompt fields <name>` to see options)
+- **Array fields** accept multiple values: `"media_type": ["cinematic", "documentary"]`
+- **Free text fields** accept any string: `"subject_description": "whatever you want"`
+
+## Use with AI agents
+
+The CLI is designed to work with AI coding agents and automation tools. Your agent builds the state JSON, pipes it to `cineprompt build`, and gets back a share link.
+
+```bash
+# Agent workflow
+echo "$STATE_JSON" | cineprompt build
+```
+
+Works with [OpenClaw](https://openclaw.ai), Claude, GPT, and any agent that can run shell commands.
+
+## Authentication
+
+API keys are scoped to share link creation only. They cannot read other users' data, access saved prompts, or modify accounts.
+
+```bash
+# Save key locally (~/.cineprompt/config.json)
+cineprompt auth cp_your_key
+
+# Or pass per-command
+cineprompt build --api-key cp_your_key '{"fields":{...}}'
+
+# Or set env var
+CINEPROMPT_API_KEY=cp_your_key cineprompt build '{"fields":{...}}'
+```
+
+## Links
+
+- [CinePrompt](https://cineprompt.io) — prompt builder
+- [Guides](https://cineprompt.io/guides) — articles on AI video prompting
+- [Light Owl](https://lightowl.com) — production company behind CinePrompt
+
+## License
+
+MIT

package/bin/cineprompt.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+/**
+ * CinePrompt CLI
+ * 
+ * Create AI video prompts and share links via cineprompt.io.
+ * 
+ * Usage:
+ *   cineprompt build '{"mode":"single","fields":{...}}'   → share link from state JSON
+ *   cineprompt build --file state.json                    → share link from JSON file
+ *   cat state.json | cineprompt build                     → share link from stdin
+ * 
+ * Auth:
+ *   cineprompt auth <api-key>                             → save API key locally
+ *   --api-key <key> or CINEPROMPT_API_KEY env var
+ * 
+ * Info:
+ *   cineprompt --help
+ *   cineprompt --version
+ *   cineprompt fields                                     → list all valid field names
+ *   cineprompt fields <name>                              → show values for a field
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { buildPromptText } from '../lib/prompt-builder.js';
+import { createShareLink } from '../lib/share.js';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
+// --- Config ---
+const CONFIG_DIR = join(homedir(), '.cineprompt');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+function loadConfig() {
+  try { return JSON.parse(readFileSync(CONFIG_FILE, 'utf8')); }
+  catch { return {}; }
+}
+
+function saveConfig(config) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+function resolveApiKey(args) {
+  // 1. --api-key flag
+  const idx = args.indexOf('--api-key');
+  if (idx !== -1 && args[idx + 1]) return args[idx + 1];
+  // 2. Env var
+  if (process.env.CINEPROMPT_API_KEY) return process.env.CINEPROMPT_API_KEY;
+  // 3. Saved config
+  const config = loadConfig();
+  if (config.apiKey) return config.apiKey;
+  return null;
+}
+
+// --- Commands ---
+
+async function cmdAuth(args) {
+  const key = args[0];
+  if (!key || !key.startsWith('cp_')) {
+    console.error('Usage: cineprompt auth <api-key>');
+    console.error('Get your API key at cineprompt.io → Settings → API Access');
+    process.exit(1);
+  }
+  saveConfig({ ...loadConfig(), apiKey: key });
+  console.log('✓ API key saved to ~/.cineprompt/config.json');
+}
+
+async function cmdBuild(args) {
+  const apiKey = resolveApiKey(args);
+  if (!apiKey) {
+    console.error('No API key. Set one with:');
+    console.error('  cineprompt auth <your-api-key>');
+    console.error('  --api-key <key>');
+    console.error('  CINEPROMPT_API_KEY=<key>');
+    console.error('');
+    console.error('Get your key at cineprompt.io → Settings → API Access (Pro required)');
+    process.exit(1);
+  }
+
+  let stateJson;
+
+  // --file flag
+  const fileIdx = args.indexOf('--file');
+  if (fileIdx !== -1 && args[fileIdx + 1]) {
+    stateJson = JSON.parse(readFileSync(args[fileIdx + 1], 'utf8'));
+  }
+  // Inline JSON argument (skip flags)
+  else {
+    const jsonArg = args.find(a => !a.startsWith('--') && a !== args[args.indexOf('--api-key') + 1]);
+    if (jsonArg) {
+      try { stateJson = JSON.parse(jsonArg); }
+      catch { /* not JSON, ignore */ }
+    }
+  }
+
+  // Stdin
+  if (!stateJson && !process.stdin.isTTY) {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    const input = Buffer.concat(chunks).toString().trim();
+    if (input) stateJson = JSON.parse(input);
+  }
+
+  if (!stateJson) {
+    console.error('No state JSON provided. Use:');
+    console.error('  cineprompt build \'{"mode":"single","fields":{...}}\'');
+    console.error('  cineprompt build --file state.json');
+    console.error('  cat state.json | cineprompt build');
+    process.exit(1);
+  }
+
+  // Ensure required structure
+  if (!stateJson.fields) {
+    console.error('Error: state JSON must have a "fields" object.');
+    process.exit(1);
+  }
+  stateJson.mode = stateJson.mode || 'single';
+  stateJson.complexity = stateJson.complexity || 'simple';
+
+  const promptText = buildPromptText(stateJson);
+  if (!promptText) {
+    console.error('Error: no prompt text generated. Check your field values.');
+    process.exit(1);
+  }
+
+  try {
+    const result = await createShareLink(apiKey, stateJson, promptText, stateJson.mode);
+    console.log(`🎬 ${result.url}`);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+function cmdFields(args) {
+  const fieldValues = require('../data/field-values.json');
+  const fieldName = args[0];
+
+  if (fieldName) {
+    const values = fieldValues[fieldName];
+    if (!values) {
+      console.error(`Unknown field: ${fieldName}`);
+      console.error(`Run "cineprompt fields" to see all field names.`);
+      process.exit(1);
+    }
+    if (Array.isArray(values)) {
+      values.forEach(v => console.log(`  ${v}`));
+    } else {
+      console.log(JSON.stringify(values, null, 2));
+    }
+  } else {
+    const names = Object.keys(fieldValues);
+    console.log(`${names.length} fields available:\n`);
+    names.forEach(n => {
+      const v = fieldValues[n];
+      const count = Array.isArray(v) ? `(${v.length} options)` : '(free text)';
+      console.log(`  ${n} ${count}`);
+    });
+    console.log(`\nRun "cineprompt fields <name>" to see values for a field.`);
+  }
+}
+
+function showHelp() {
+  console.log(`
+cineprompt v${pkg.version} — AI video prompt builder
+
+Commands:
+  build <json>           Create a share link from state JSON
+  build --file <path>    Create a share link from a JSON file
+  auth <api-key>         Save your API key locally
+  fields                 List all valid field names
+  fields <name>          Show valid values for a field
+
+Options:
+  --api-key <key>        Use this API key (or set CINEPROMPT_API_KEY)
+  --version, -v          Show version
+  --help, -h             Show this help
+
+Examples:
+  cineprompt auth cp_abc123
+  cineprompt build '{"mode":"single","complexity":"complex","subjectType":"landscape","fields":{"media_type":["cinematic"],"env_time":"golden hour, warm late afternoon light"}}'
+  cat shot.json | cineprompt build
+
+Get your API key: cineprompt.io → Settings → API Access (Pro required)
+Docs: cineprompt.io/guides
+`.trim());
+}
+
+// --- Main ---
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+if (!cmd || cmd === '--help' || cmd === '-h') {
+  showHelp();
+} else if (cmd === '--version' || cmd === '-v') {
+  console.log(pkg.version);
+} else if (cmd === 'auth') {
+  cmdAuth(args.slice(1));
+} else if (cmd === 'build') {
+  cmdBuild(args.slice(1));
+} else if (cmd === 'fields') {
+  cmdFields(args.slice(1));
+} else {
+  console.error(`Unknown command: ${cmd}`);
+  console.error('Run "cineprompt --help" for usage.');
+  process.exit(1);
+}