@a9s/cli 0.0.1 → 0.1.0

package/README.md

@@ -1,3 +1,168 @@
-# @a9s/cli
+# a9s
 
-Name reserved on npm. Official package coming soon.
+![npm version](https://img.shields.io/npm/v/@a9s/cli) ![CI](https://img.shields.io/github/actions/workflow/status/IamShobe/a9s/ci.yaml?label=CI) ![GitHub release](https://img.shields.io/github/v/release/IamShobe/a9s)
+
+**k9s-style TUI navigator for AWS services.** Inspired by [k9s](https://github.com/derailed/k9s).
+
+## Installation
+
+### Global install (recommended)
+
+```shell
+npm install -g @a9s/cli
+a9s
+```
+
+### Local install + npx
+
+```shell
+npm install @a9s/cli
+npx @a9s/cli
+```
+
+## Usage
+
+Launch the TUI:
+
+```shell
+a9s
+```
+
+### Navigation
+
+- **Arrow keys / hjkl**: Navigate between rows
+- **Tab**: Switch between columns (sort/filter)
+- **Enter**: Drill into details or navigate to the next level
+- **Backspace**: Go back to the previous level
+- **/** (slash): Search/filter current view
+- **:**: Command mode (e.g., `:services` to list available services)
+- **?**: Show help panel with all keybindings for current context
+
+### Service Switching
+
+Press `:services` to see the list of available AWS services and switch between them.
+
+### Common Operations
+
+- **d**: Open detail panel for selected row (shows metadata like ARN, tags, etc.)
+- **y + key**: Yank/copy shortcuts:
+  - `y+n` → copy name
+  - `y+a` → copy ARN
+  - `y+k` → copy S3 key or other identifiers
+- **f**: Fetch/download S3 objects to local path
+- **e**: Edit and upload (opens selected item in `$EDITOR`)
+- **v**: Toggle reveal/hide secrets (Secrets Manager)
+
+## Services Supported
+
+| Service         | Status | Features                                        |
+| --------------- | ------ | ----------------------------------------------- |
+| S3              | ✅     | Browse buckets, objects, download, edit, delete |
+| IAM             | ✅     | List users, roles, policies                     |
+| Route 53        | ✅     | List hosted zones, records                      |
+| Secrets Manager | ✅     | View, edit, and upload secrets                  |
+| DynamoDB        | ✅     | List tables, view items                         |
+
+## Features
+
+- **Responsive tables** with sortable columns
+- **Service switching** with `:services` command
+- **VIM-inspired shortcuts** (hjkl navigation, commands)
+- **Yank mode** for quick copy operations
+- **Detail panels** showing rich metadata
+- **In-editor editing** with upload confirmation
+- **Search/filter** with `/` key
+- **Help system** with context-sensitive keybindings
+- **LocalStack support** for offline development
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- pnpm (for package management)
+- Docker (for LocalStack)
+
+### Setup
+
+```bash
+pnpm install
+```
+
+### Run Against LocalStack
+
+Start LocalStack + seed data:
+
+```bash
+pnpm localstack:setup
+```
+
+Run the TUI (connects to LocalStack on port 4566):
+
+```bash
+pnpm dev:local
+```
+
+### Run Against AWS
+
+Connect to your AWS account:
+
+```bash
+pnpm dev
+```
+
+This will use your `~/.aws/credentials` and `AWS_REGION` environment variable.
+
+### Testing
+
+```bash
+pnpm test       # Run tests
+pnpm typecheck  # Type checking
+pnpm build      # Build TypeScript to dist/
+```
+
+### Project Structure
+
+```
+src/
+  index.tsx          - CLI entry point (commander)
+  App.tsx            - Main TUI state machine & layout
+  types.ts           - Core types (ColumnDef, TableRow, etc.)
+  services.ts        - Service registry
+  adapters/          - ServiceAdapter implementations for each AWS service
+  views/             - Service-specific views (s3, iam, route53, dynamodb, secretsmanager)
+  components/        - Ink/React components (Table, HUD, DetailPanel, etc.)
+  hooks/             - Custom React hooks (navigation, state, etc.)
+  constants/         - Keybindings, commands
+scripts/
+  seed.ts            - LocalStack test data seeding
+docker/
+  docker-compose.yml - LocalStack with services
+```
+
+## Goals
+
+### Services (Planned)
+
+- [x] S3
+- [x] IAM
+- [x] Route 53
+- [x] DynamoDB
+- [x] Secrets Manager
+- [ ] EC2
+- [ ] ELB
+- [ ] CloudFront
+
+### Features (Planned)
+
+- [x] Responsive tables
+- [x] Service switching
+- [x] VIM shortcuts
+- [x] Yank operations
+- [x] Detail panels
+- [x] Edit & upload
+- [ ] Smart cross-service navigation (e.g., Route53 → ELB)
+
+## License
+
+MIT

package/dist/scripts/seed.js

@@ -0,0 +1,310 @@
+import { S3Client, CreateBucketCommand, PutObjectCommand, ListBucketsCommand, } from "@aws-sdk/client-s3";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const client = new S3Client({
+    endpoint: "http://localhost:4566",
+    forcePathStyle: true,
+    region: "us-east-1",
+    credentials: { accessKeyId: "test", secretAccessKey: "test" },
+});
+const BUCKETS = [
+    "my-app-logs",
+    "data-warehouse",
+    "static-assets",
+    "backups-prod",
+    "ml-datasets",
+    "user-uploads",
+    "audit-trail",
+    "terraform-state",
+    "build-artifacts",
+    "media-storage",
+];
+const OBJECT_TEMPLATES = [
+    "logs/{year}/{month}/app.log",
+    "logs/{year}/{month}/error.log",
+    "data/users.json",
+    "data/products.json",
+    "data/{year}/export.csv",
+    "config/settings.yaml",
+    "config/secrets.json.enc",
+    "reports/{year}/{month}/summary.pdf",
+    "images/avatars/{id}.png",
+    "images/banners/hero.jpg",
+    "scripts/deploy.sh",
+    "scripts/migrate.py",
+    "archive/{year}/backup.tar.gz",
+    "tmp/processing/{id}.tmp",
+    "public/index.html",
+    "public/styles.css",
+    "public/bundle.js",
+];
+function randomInt(min, max) {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+function renderTemplate(template) {
+    return template
+        .replace("{year}", String(randomInt(2022, 2024)))
+        .replace("{month}", String(randomInt(1, 12)).padStart(2, "0"))
+        .replace("{id}", Math.random().toString(36).slice(2, 10));
+}
+async function ensureBucket(name) {
+    try {
+        await client.send(new CreateBucketCommand({ Bucket: name }));
+        console.log(`  Created bucket: ${name}`);
+    }
+    catch (e) {
+        const err = e;
+        if (err.name === "BucketAlreadyOwnedByYou" || err.name === "BucketAlreadyExists") {
+            console.log(`  Bucket already exists: ${name}`);
+        }
+        else {
+            throw e;
+        }
+    }
+}
+async function seedBucket(bucket) {
+    const count = randomInt(0, 30);
+    const templates = [...OBJECT_TEMPLATES].sort(() => Math.random() - 0.5).slice(0, count);
+    for (const tpl of templates) {
+        const key = renderTemplate(tpl);
+        const content = `Seeded content for ${key} in ${bucket}\n`;
+        await client.send(new PutObjectCommand({
+            Bucket: bucket,
+            Key: key,
+            Body: content,
+            ContentType: "text/plain",
+        }));
+        process.stdout.write(".");
+    }
+    if (count > 0)
+        console.log(` ${count} objects`);
+    else
+        console.log(" (empty)");
+}
+async function checkLocalStack() {
+    try {
+        await client.send(new ListBucketsCommand({}));
+    }
+    catch {
+        console.error("Cannot connect to LocalStack at http://localhost:4566\n" +
+            "Run: pnpm localstack:up\n" +
+            "Wait a few seconds for it to start, then retry.");
+        process.exit(1);
+    }
+}
+async function runAws(args) {
+    const env = {
+        ...process.env,
+        AWS_ACCESS_KEY_ID: "test",
+        AWS_SECRET_ACCESS_KEY: "test",
+        AWS_DEFAULT_REGION: "us-east-1",
+    };
+    const { stdout } = await execFileAsync("aws", ["--endpoint-url", "http://localhost:4566", ...args], {
+        env,
+        timeout: 5000,
+    });
+    return stdout;
+}
+async function ensureManagedPolicy(policyName, policyDocument) {
+    const listOut = await runAws([
+        "iam",
+        "list-policies",
+        "--scope",
+        "Local",
+        "--query",
+        `Policies[?PolicyName=='${policyName}'].Arn | [0]`,
+        "--output",
+        "text",
+    ]);
+    const existingArn = listOut.trim();
+    if (existingArn && existingArn !== "None") {
+        console.log(`  Managed policy already exists: ${policyName}`);
+        return existingArn;
+    }
+    const createOut = await runAws([
+        "iam",
+        "create-policy",
+        "--policy-name",
+        policyName,
+        "--policy-document",
+        JSON.stringify(policyDocument),
+        "--output",
+        "json",
+    ]);
+    const parsed = JSON.parse(createOut);
+    const arn = parsed.Policy?.Arn;
+    if (!arn)
+        throw new Error(`Failed creating managed policy ${policyName}`);
+    console.log(`  Created managed policy: ${policyName}`);
+    return arn;
+}
+async function ensureRole(roleName, trustPolicy) {
+    const existing = await runAws([
+        "iam",
+        "get-role",
+        "--role-name",
+        roleName,
+        "--query",
+        "Role.RoleName",
+        "--output",
+        "text",
+    ]).catch(() => "");
+    if (existing.trim() === roleName) {
+        console.log(`  Role already exists: ${roleName}`);
+        return;
+    }
+    await runAws([
+        "iam",
+        "create-role",
+        "--role-name",
+        roleName,
+        "--assume-role-policy-document",
+        JSON.stringify(trustPolicy),
+    ]);
+    console.log(`  Created role: ${roleName}`);
+}
+async function ensureInlineRolePolicy(roleName, policyName, policyDocument) {
+    await runAws([
+        "iam",
+        "put-role-policy",
+        "--role-name",
+        roleName,
+        "--policy-name",
+        policyName,
+        "--policy-document",
+        JSON.stringify(policyDocument),
+    ]);
+    console.log(`  Put inline policy ${policyName} on ${roleName}`);
+}
+async function ensureAttachedRolePolicy(roleName, policyArn) {
+    const attached = await runAws([
+        "iam",
+        "list-attached-role-policies",
+        "--role-name",
+        roleName,
+        "--query",
+        `AttachedPolicies[?PolicyArn=='${policyArn}'].PolicyArn | [0]`,
+        "--output",
+        "text",
+    ]);
+    if (attached.trim() === policyArn) {
+        console.log(`  Managed policy already attached to ${roleName}`);
+        return;
+    }
+    await runAws(["iam", "attach-role-policy", "--role-name", roleName, "--policy-arn", policyArn]);
+    console.log(`  Attached managed policy to ${roleName}`);
+}
+async function seedSecretsManager() {
+    console.log("\nSeeding Secrets Manager:");
+    const secrets = [
+        { name: "app/db-password", value: "s3cr3tP@ssword123" },
+        { name: "app/api-key", value: "sk-test-abc123xyz" },
+        { name: "app/jwt-secret", value: "super-secret-jwt-key-do-not-share" },
+        { name: "infra/config", value: JSON.stringify({ host: "localhost", port: 5432, db: "app" }) },
+        {
+            name: "prod/tls-cert",
+            value: "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
+        },
+        { name: "monitoring/grafana-api-key", value: "glsa_test123456" },
+    ];
+    for (const secret of secrets) {
+        try {
+            await runAws([
+                "secretsmanager",
+                "create-secret",
+                "--name",
+                secret.name,
+                "--secret-string",
+                secret.value,
+            ]);
+            console.log(`  Created secret: ${secret.name}`);
+        }
+        catch (e) {
+            const err = e;
+            if (err.message?.includes("ResourceExistsException")) {
+                console.log(`  Secret already exists: ${secret.name}`);
+            }
+            else {
+                throw e;
+            }
+        }
+    }
+}
+async function seedIam() {
+    console.log("\nSeeding IAM:");
+    const trustPolicy = {
+        Version: "2012-10-17",
+        Statement: [
+            {
+                Effect: "Allow",
+                Principal: { Service: "ec2.amazonaws.com" },
+                Action: "sts:AssumeRole",
+            },
+        ],
+    };
+    const appReadPolicy = {
+        Version: "2012-10-17",
+        Statement: [
+            {
+                Sid: "ReadSomeBuckets",
+                Effect: "Allow",
+                Action: ["s3:GetObject", "s3:ListBucket"],
+                Resource: [
+                    "arn:aws:s3:::media-storage",
+                    "arn:aws:s3:::media-storage/*",
+                    "arn:aws:s3:::static-assets",
+                    "arn:aws:s3:::static-assets/*",
+                ],
+            },
+        ],
+    };
+    const auditPolicy = {
+        Version: "2012-10-17",
+        Statement: [
+            {
+                Sid: "AuditReadOnly",
+                Effect: "Allow",
+                Action: ["s3:GetObject", "s3:ListBucket"],
+                Resource: ["arn:aws:s3:::audit-trail", "arn:aws:s3:::audit-trail/*"],
+            },
+        ],
+    };
+    const inlineDeployPolicy = {
+        Version: "2012-10-17",
+        Statement: [
+            {
+                Sid: "WriteBuildArtifacts",
+                Effect: "Allow",
+                Action: ["s3:PutObject", "s3:DeleteObject", "s3:GetObject"],
+                Resource: ["arn:aws:s3:::build-artifacts/*"],
+            },
+        ],
+    };
+    const readPolicyArn = await ensureManagedPolicy("A9SAppReadPolicy", appReadPolicy);
+    const auditPolicyArn = await ensureManagedPolicy("A9SAuditPolicy", auditPolicy);
+    await ensureRole("A9SAppRole", trustPolicy);
+    await ensureRole("A9SReadOnlyRole", trustPolicy);
+    await ensureInlineRolePolicy("A9SAppRole", "A9SInlineDeployPolicy", inlineDeployPolicy);
+    await ensureAttachedRolePolicy("A9SAppRole", readPolicyArn);
+    await ensureAttachedRolePolicy("A9SReadOnlyRole", auditPolicyArn);
+}
+async function main() {
+    console.log("Checking LocalStack connection...");
+    await checkLocalStack();
+    console.log("Connected!\n");
+    for (const bucket of BUCKETS) {
+        console.log(`Seeding ${bucket}:`);
+        await ensureBucket(bucket);
+        process.stdout.write("  Objects: ");
+        await seedBucket(bucket);
+    }
+    await seedIam();
+    await seedSecretsManager();
+    console.log("\nDone! LocalStack seeded with test data.");
+    console.log("Run: pnpm dev:local");
+}
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});