@sarthak_krishak/inkforge 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+```
+MIT License
+
+Copyright (c) 2026 Sarthak
+
+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,189 @@
+# InkForge
+
+> **Beautiful, customizable terminal UI components — installed in one command, owned forever.**
+
+InkForge is a copy-paste component library for building Terminal UIs with [React](https://react.dev) and [Ink](https://github.com/vadimdemedes/ink). Think of it as **shadcn/ui for your terminal** — instead of installing a locked npm dependency, you get the actual source code dropped into your project. You own it. You can read it, edit it, delete it.
+
+```bash
+npx inkforge add spinner
+npx inkforge add progressbar
+npx inkforge add spinner progressbar
+```
+
+---
+
+## Why InkForge?
+
+Modern AI coding tools (Claude Code, Aider, OpenCode) live in the terminal — but building beautiful terminal UIs from scratch is painful. Every developer reinvents spinners, progress bars, and diff viewers from raw ANSI escape codes.
+
+InkForge solves this with a simple philosophy:
+
+| Principle | What it means |
+|---|---|
+| **Own your code** | `npx inkforge add spinner` drops the actual `.jsx` file into your project — no runtime dependency |
+| **Copy-paste first** | Every component is plain, readable JSX. No magic. No black boxes. |
+| **AI-native by default** | Built for the components AI coding agents actually need |
+| **Terminal-aware** | Designed for ANSI constraints and tested on real terminals |
+
+---
+
+## Installation
+
+InkForge has no runtime dependency. You use the CLI once to copy components into your project, then the CLI is no longer needed.
+
+Your project needs these peer dependencies:
+
+```bash
+npm install react ink
+```
+
+---
+
+## Usage
+
+### Interactive mode (recommended)
+
+Run with no arguments to get an interactive component selector:
+
+```bash
+npx inkforge add
+```
+
+Use `↑↓` to move, `space` to select, `enter` to confirm.
+
+### Direct mode
+
+Add components by name:
+
+```bash
+npx inkforge add spinner
+npx inkforge add progressbar
+npx inkforge add spinner progressbar   # multiple at once
+```
+
+### List all components
+
+```bash
+npx inkforge list
+```
+
+---
+
+## Components
+
+### `Spinner`
+
+Animated loading indicator with 5 variants and theme support.
+
+```jsx
+import { Spinner } from './components/inkforge/Spinner';
+
+// Basic
+<Spinner label="Loading..." />
+
+// Variants: dots | line | bounce | arc | simple
+<Spinner variant="bounce" label="Processing..." />
+
+// Themes: default | cyberpunk
+<Spinner variant="dots" theme="cyberpunk" label="Hacking..." />
+
+// Done state
+<Spinner label="Deploying..." done={isDone} doneText="✓ Deployed!" />
+```
+
+**Props**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `string` | `'dots'` | Animation style: `dots`, `line`, `bounce`, `arc`, `simple` |
+| `label` | `string` | `'Loading...'` | Text shown next to spinner |
+| `color` | `string` | theme primary | Override spinner color (hex or named) |
+| `theme` | `string` | `'default'` | Color theme: `default`, `cyberpunk` |
+| `interval` | `number` | `80` | Animation speed in ms |
+| `done` | `boolean` | `false` | Switch to completion state |
+| `doneText` | `string` | `'✓ Done'` | Text shown when `done` is true |
+
+---
+
+### `ProgressBar`
+
+Fillable progress bar with 3 visual variants.
+
+```jsx
+import { ProgressBar } from './components/inkforge/ProgressBar';
+
+// Basic
+<ProgressBar value={60} label="Build" />
+
+// Show raw value instead of percent
+<ProgressBar value={45} total={200} label="Files" showValue />
+
+// Variants: default | thin | block
+<ProgressBar value={progress} variant="thin"  label="Upload" />
+<ProgressBar value={progress} variant="block" label="Memory" />
+
+// Custom color
+<ProgressBar value={progress} color="#E5C07B" label="CPU" />
+```
+
+**Props**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `number` | `0` | Current progress value |
+| `total` | `number` | `100` | Maximum value |
+| `width` | `number` | `30` | Bar width in characters |
+| `label` | `string` | `''` | Label shown before the bar |
+| `showPercent` | `boolean` | `true` | Show `%` on the right |
+| `showValue` | `boolean` | `false` | Show `value/total` instead |
+| `color` | `string` | theme success | Fill color |
+| `bgColor` | `string` | theme muted | Empty bar color |
+| `theme` | `string` | `'default'` | Color theme: `default`, `cyberpunk` |
+| `variant` | `string` | `'default'` | Bar style: `default`, `thin`, `block` |
+
+---
+
+## Themes
+
+InkForge ships with two pre-built themes. Pass `theme` to any component:
+
+| Theme | Description | Best for |
+|---|---|---|
+| `default` | Clean, professional, blue accent | Production tools |
+| `cyberpunk` | High contrast, neon cyan/magenta | Dev tools, personal projects |
+
+---
+
+## Roadmap
+
+- [x] Spinner
+- [x] ProgressBar
+- [ ] DiffViewer — AI-native code diff display
+- [ ] StreamingOutput — Token-by-token streaming display
+- [ ] PromptInput — Input with history and autocomplete
+- [ ] Select / MultiSelect — Keyboard-navigable menus
+- [ ] Table — Structured data display
+- [ ] StatusBar — Footer with agent state
+
+---
+
+## Contributing
+
+Contributions are welcome. Open an issue first to discuss what you'd like to add.
+
+```bash
+git clone https://github.com/yourusername/inkforge
+cd inkforge
+npm install
+npm run demo    # See components in action
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE)
+
+---
+
+*Built for the era of AI coding agents. Inspired by [shadcn/ui](https://ui.shadcn.com).*

package/cli/index.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+
+// cli/index.js — inkforge CLI
+// Usage: npx inkforge add <component>
+//        npx inkforge list
+
+import { program } from 'commander';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import readline from 'readline';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ─── Color helpers (no chalk dependency needed for CLI) ───────────────────────
+const c = {
+  cyan:   s => `\x1b[36m${s}\x1b[0m`,
+  green:  s => `\x1b[32m${s}\x1b[0m`,
+  yellow: s => `\x1b[33m${s}\x1b[0m`,
+  red:    s => `\x1b[31m${s}\x1b[0m`,
+  bold:   s => `\x1b[1m${s}\x1b[0m`,
+  dim:    s => `\x1b[2m${s}\x1b[0m`,
+  reset:  s => `\x1b[0m${s}\x1b[0m`,
+};
+
+// ─── Component registry ───────────────────────────────────────────────────────
+const REGISTRY = {
+  spinner: {
+    name:        'Spinner',
+    description: 'Animated loading spinner with 5 variants',
+    file:        'Spinner/index.jsx',
+    dir:         'Spinner',
+    usage:       "<Spinner variant=\"dots\" label=\"Loading...\" />",
+  },
+  progressbar: {
+    name:        'ProgressBar',
+    description: 'Fillable progress bar with 3 variants',
+    file:        'ProgressBar/index.jsx',
+    dir:         'ProgressBar',
+    usage:       "<ProgressBar value={60} label=\"Build\" />",
+  },
+};
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function getComponentsDir() {
+  const cwd = process.cwd();
+  // Try src/components first, then components/
+  const candidates = [
+    path.join(cwd, 'src', 'components', 'inkforge'),
+    path.join(cwd, 'components', 'inkforge'),
+  ];
+  // Return the first parent that exists, defaulting to src/components/inkforge
+  if (fs.existsSync(path.join(cwd, 'src'))) return candidates[0];
+  return candidates[1];
+}
+
+function getTemplatesDir() {
+  return path.join(__dirname, '..', 'src', 'components');
+}
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function copyComponent(key) {
+  const entry      = REGISTRY[key];
+  const srcDir     = getTemplatesDir();
+  const destDir    = getComponentsDir();
+  const srcFile    = path.join(srcDir, entry.file);
+  const destFolder = path.join(destDir, entry.dir);
+  const destFile   = path.join(destFolder, 'index.jsx');
+
+  // Check template exists (guards against broken installs)
+  if (!fs.existsSync(srcFile)) {
+    console.log(c.red(`✗ Template not found for ${entry.name}. Try reinstalling inkforge.`));
+    return false;
+  }
+
+  // Warn if already exists
+  if (fs.existsSync(destFile)) {
+    console.log(c.yellow(`⚠  ${entry.name} already exists at ${path.relative(process.cwd(), destFile)}`));
+    console.log(c.dim('   Skipping. Delete the file first if you want a fresh copy.\n'));
+    return false;
+  }
+
+  ensureDir(destFolder);
+
+  // Read template and rewrite the import path to be relative to the user's project
+  let src = fs.readFileSync(srcFile, 'utf8');
+  // Replace the internal core path with a sensible relative path
+  src = src.replace(
+    /from ['"].*?core\/colors\.js['"]/,
+    `from '../core/colors.js'`
+  );
+
+  fs.writeFileSync(destFile, src, 'utf8');
+
+  // Also copy core/colors.js if not present
+  ensureCoreColors(destDir);
+
+  console.log(c.green(`✓ Added ${c.bold(entry.name)}`));
+  console.log(c.dim(`  → ${path.relative(process.cwd(), destFile)}\n`));
+  console.log(c.cyan('  Usage:'));
+  console.log(c.dim(`  import { ${entry.name} } from './${path.relative(process.cwd(), destFolder).replace(/\\/g, '/')}';`));
+  console.log(c.dim(`  ${entry.usage}\n`));
+  return true;
+}
+
+function ensureCoreColors(destDir) {
+  const coreDir  = path.join(destDir, 'core');
+  const destFile = path.join(coreDir, 'colors.js');
+  if (fs.existsSync(destFile)) return;
+
+  const srcFile = path.join(__dirname, '..', 'src', 'core', 'colors.js');
+  if (!fs.existsSync(srcFile)) return;
+
+  ensureDir(coreDir);
+  fs.copyFileSync(srcFile, destFile);
+  console.log(c.dim(`  → Also copied core/colors.js\n`));
+}
+
+// ─── Interactive selector ─────────────────────────────────────────────────────
+async function interactiveSelect() {
+  const keys    = Object.keys(REGISTRY);
+  const entries = keys.map(k => REGISTRY[k]);
+  let   cursor  = 0;
+  const selected = new Set();
+
+  // Hide cursor, enable raw mode
+  process.stdout.write('\x1b[?25l');
+  readline.emitKeypressEvents(process.stdin);
+  if (process.stdin.isTTY) process.stdin.setRawMode(true);
+
+  function render() {
+    // Clear previous lines
+    process.stdout.write(`\x1b[${entries.length + 4}A\x1b[0J`);
+    console.log(c.bold('\n  Select components to add:\n'));
+    entries.forEach((e, i) => {
+      const checked  = selected.has(keys[i]) ? c.green('◉') : c.dim('○');
+      const active   = i === cursor ? c.cyan('▶ ') : '  ';
+      const name     = i === cursor ? c.bold(c.cyan(e.name)) : e.name;
+      const desc     = c.dim(e.description);
+      console.log(`  ${active}${checked}  ${name.padEnd(18)}${desc}`);
+    });
+    console.log(c.dim('\n  ↑↓ move  space select  enter confirm  q quit'));
+  }
+
+  // Initial render — print blank lines first so clear works
+  console.log('\n');
+  entries.forEach(() => console.log(''));
+  console.log('\n');
+  render();
+
+  return new Promise(resolve => {
+    process.stdin.on('keypress', (str, key) => {
+      if (!key) return;
+
+      if (key.name === 'up')   cursor = (cursor - 1 + keys.length) % keys.length;
+      if (key.name === 'down') cursor = (cursor + 1) % keys.length;
+
+      if (key.name === 'space') {
+        const k = keys[cursor];
+        if (selected.has(k)) selected.delete(k);
+        else selected.add(k);
+      }
+
+      if (key.name === 'return') {
+        cleanup();
+        resolve([...selected]);
+      }
+
+      if (key.name === 'q' || (key.ctrl && key.name === 'c')) {
+        cleanup();
+        console.log(c.dim('\n  Cancelled.\n'));
+        resolve([]);
+      }
+
+      render();
+    });
+  });
+
+  function cleanup() {
+    if (process.stdin.isTTY) process.stdin.setRawMode(false);
+    process.stdin.pause();
+    process.stdout.write('\x1b[?25h'); // show cursor
+  }
+}
+
+// ─── Commands ─────────────────────────────────────────────────────────────────
+program
+  .name('inkforge')
+  .description('InkForge — beautiful terminal UI components for React/Ink')
+  .version('0.1.0');
+
+// inkforge list
+program
+  .command('list')
+  .description('List all available components')
+  .action(() => {
+    console.log(c.bold('\n  InkForge Components\n'));
+    Object.entries(REGISTRY).forEach(([key, entry]) => {
+      console.log(`  ${c.cyan(entry.name.padEnd(16))} ${c.dim(entry.description)}`);
+      console.log(c.dim(`  npx inkforge add ${key}\n`));
+    });
+  });
+
+// inkforge add [component...]
+program
+  .command('add [components...]')
+  .description('Add one or more components to your project')
+  .action(async (components) => {
+    console.log(c.bold(c.cyan('\n  InkForge\n')));
+
+    // No args — show interactive selector
+    if (!components || components.length === 0) {
+      const chosen = await interactiveSelect();
+      if (chosen.length === 0) return;
+      console.log('');
+      chosen.forEach(key => copyComponent(key));
+      return;
+    }
+
+    // Args provided — add them directly
+    let anyFailed = false;
+    for (const name of components) {
+      const key = name.toLowerCase().replace(/[^a-z]/g, '');
+      if (!REGISTRY[key]) {
+        console.log(c.red(`✗ Unknown component: "${name}"`));
+        console.log(c.dim(`  Run ${c.cyan('npx inkforge list')} to see available components.\n`));
+        anyFailed = true;
+        continue;
+      }
+      copyComponent(key);
+    }
+
+    if (!anyFailed) {
+      console.log(c.green(c.bold('  All done! Components are yours to own and edit.\n')));
+    }
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@sarthak_krishak/inkforge",
+  "version": "0.1.0",
+  "description": "Beautiful terminal UI components for React/Ink — shadcn/ui for your terminal",
+  "type": "module",
+  "main": "src/index.jsx",
+  "bin": {
+    "inkforge": "./cli/index.js"
+  },
+  "files": [
+    "src/",
+    "cli/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "terminal",
+    "tui",
+    "ink",
+    "cli",
+    "react",
+    "spinner",
+    "progress",
+    "shadcn"
+  ],
+  "author": "Sarthak Krishak",
+  "license": "MIT",
+  "peerDependencies": {
+    "ink": ">=5.0.0",
+    "react": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.0",
+    "ink": "^5.0.0",
+    "react": "^18.3.0",
+    "vite": "^5.4.0",
+    "vite-node": "^2.1.0"
+  }
+}

package/src/components/ProgressBar/index.jsx

@@ -0,0 +1,46 @@
+import React from 'react';
+import { Text, Box } from 'ink';
+import { getTheme } from '../../core/colors.js';
+
+export function ProgressBar({
+  value       = 0,
+  total       = 100,
+  width       = 30,
+  label       = '',
+  showPercent = true,
+  showValue   = false,
+  color       = null,
+  bgColor     = null,
+  theme       = 'default',
+  variant     = 'default',
+}) {
+  const palette    = getTheme(theme);
+  const fillColor  = color   || palette.success;
+  const emptyColor = bgColor || palette.muted;
+
+  const percent   = Math.min(100, Math.max(0, (value / total) * 100));
+  const filled    = Math.round((percent / 100) * width);
+  const empty     = width - filled;
+
+  const chars = {
+    default: { fill: '█', empty: '░' },
+    thin:    { fill: '─', empty: '┄' },
+    block:   { fill: '■', empty: '□' },
+  }[variant] || { fill: '█', empty: '░' };
+
+  const filledBar = chars.fill.repeat(filled);
+  const emptyBar  = chars.empty.repeat(empty);
+
+  let rightLabel = '';
+  if (showValue)        rightLabel = ` ${value}/${total}`;
+  else if (showPercent) rightLabel = ` ${Math.round(percent)}%`;
+
+  return (
+    <Box>
+      {label ? <Text color={palette.text}>{label} </Text> : null}
+      <Text color={fillColor}>{filledBar}</Text>
+      <Text color={emptyColor}>{emptyBar}</Text>
+      <Text color={palette.text}>{rightLabel}</Text>
+    </Box>
+  );
+}

package/src/components/Spinner/index.jsx

@@ -0,0 +1,48 @@
+import React, { useState, useEffect } from 'react';
+import { Text, Box } from 'ink';
+import { getTheme } from '../../core/colors.js';
+
+const VARIANTS = {
+  dots:   ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'],
+  line:   ['—','\\','|','/'],
+  bounce: ['⣾','⣽','⣻','⢿','⡿','⣟','⣯','⣷'],
+  arc:    ['◜','◠','◝','◞','◡','◟'],
+  simple: ['.  ','.. ','...','   '],
+};
+
+export function Spinner({
+  variant  = 'dots',
+  label    = 'Loading...',
+  color    = null,
+  theme    = 'default',
+  interval = 120,
+  done     = false,
+  doneText = '✓ Done',
+}) {
+  const [frame, setFrame] = useState(0);
+  const frames   = VARIANTS[variant] || VARIANTS.dots;
+  const palette  = getTheme(theme);
+  const spinnerColor = color || palette.primary;
+
+  useEffect(() => {
+    if (done) return;
+    // Use a ref-tracked interval so it doesn't chain re-renders
+    let f = 0;
+    const timer = setInterval(() => {
+      f = (f + 1) % frames.length;
+      setFrame(f);
+    }, interval);
+    return () => clearInterval(timer);
+  }, [done, variant, interval]);  // only re-subscribe if these change
+
+  if (done) {
+    return <Box><Text color={palette.success}>{doneText}</Text></Box>;
+  }
+
+return (
+    <Box>
+      <Text color={spinnerColor}>{frames[frame]} </Text>
+      <Text color={palette.text}>{label}</Text>
+    </Box>
+  );
+}

package/src/core/colors.js

@@ -0,0 +1,25 @@
+// src/core/colors.js
+const themes = {
+  default: {
+    primary: '#61AFEF',
+    success: '#98C379',
+    warning: '#E5C07B',
+    error:   '#E06C75',
+    muted:   '#5C6370',
+    text:    '#ABB2BF',
+    bright:  '#FFFFFF',
+  },
+  cyberpunk: {
+    primary: '#00FFFF',
+    success: '#00FF88',
+    warning: '#FFD700',
+    error:   '#FF5555',
+    muted:   '#444466',
+    text:    '#CCCCFF',
+    bright:  '#FFFFFF',
+  },
+};
+
+export function getTheme(name = 'default') {
+  return themes[name] || themes.default;
+}

package/src/index.jsx

@@ -0,0 +1,3 @@
+// src/index.jsx
+export { Spinner }     from './components/Spinner/index.jsx';
+export { ProgressBar } from './components/ProgressBar/index.jsx';