lhumina_code/hero_codesmith
22
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions

rename spec 3 #5

New issue
Open
opened 2026-03-10 06:30:15 +00:00 by despiegk · 1 comment
despiegk commented 2026-03-10 06:30:15 +00:00
Owner
Copy link

use skill /hero_crates_best_practices_check

put a readme in each of the folders

organize the repo well

initial start

./crates/codesmith_ui
./crates/codesmith_lib
./crates/codesmiths_server
./crates/codesmith_ssh
./crates/codesmith

put a spec document in each directory (SPECIFICATIONS.md)

Here is a minimal spec for CodeSmith.

CodeSmith — Minimal Specification

1. Purpose

CodeSmith is a remote development orchestration module that prepares and manages secure development environments on remote servers over SSH.

Its first goal is simple:

  • connect to remote machines over SSH
  • install and run a small CodeSmith server on each machine
  • expose that server locally through SSH forwarding to a local socket
  • treat each forwarded local socket as a controllable remote development node
  • let the node create and manage isolated development users and workspaces

This is only the skeleton for further work.

2. High-Level Concept

CodeSmith consists of two parts:

2.1 Local controller

Runs on the operator/developer machine.

Responsibilities:

  • connect to remote nodes over SSH
  • bootstrap the remote CodeSmith server
  • maintain SSH tunnels / port forwards / socket forwards
  • expose each remote node as a local endpoint
  • talk to the remote server over OpenRPC
  • orchestrate multiple nodes uniformly

2.2 Remote CodeSmith server

Runs on each managed server.

Responsibilities:

  • expose an OpenRPC API
  • create and manage system users for secure development
  • create and manage isolated workspaces / sandboxes
  • organize code checkout / initialization
  • provide basic lifecycle operations for development environments
  • operate with least privilege where possible

3. Core Design Principles

3.1 SSH-first

No public service exposure is required initially.

All communication happens through:

  • SSH for bootstrap and transport
  • local forwarded socket for API access

3.2 OpenRPC-native

All remote operations are exposed through a clear OpenRPC interface.

This allows:

  • strong typing
  • code generation
  • compatibility with internal tooling
  • later extension to agents and automation

3.3 Secure-by-default

Development happens in isolated contexts.

Initial security model:

  • one or more dedicated users per workspace or task
  • no direct use of root except where unavoidable during setup
  • clear separation between controller identity and sandbox identity
  • filesystem and process isolation boundaries defined early

3.4 Workspace-oriented

The primary unit of work is a workspace.

A workspace contains:

  • code
  • configuration
  • user context
  • sandbox/runtime information
  • metadata needed for AI-assisted development

4. Initial Scope

The first version only needs to support:

4.1 Node preparation

Prepare a target server over SSH so it can run CodeSmith.

Includes:

  • checking OS compatibility
  • installing required dependencies
  • creating required directories
  • installing or updating the CodeSmith server binary/service
  • configuring service startup
  • preparing permissions

4.2 Remote server startup

Ensure the CodeSmith server is running on the node.

Includes:

  • start
  • stop
  • restart
  • health check
  • version check

4.3 Local forwarding

Forward the remote CodeSmith API endpoint to a local socket.

Examples:

  • local Unix socket
  • local localhost TCP port

The controller should maintain a mapping such as:

  • local socket A -> remote node 1
  • local socket B -> remote node 2

4.4 User management

Remote server can:

  • create development users
  • inspect users created by CodeSmith
  • delete or disable development users
  • enforce ownership and permissions for workspaces

4.5 Workspace management

Remote server can:

  • create workspace
  • list workspaces
  • open existing workspace
  • delete workspace
  • assign workspace to a user
  • initialize directory structure

4.6 Sandbox skeleton

Remote server can create a minimal isolated execution context.

At this stage, sandbox may simply mean:

  • dedicated Unix user
  • dedicated workspace directory
  • restricted permissions
  • optional process isolation to be added later

5. Non-Goals for the First Skeleton

Not required yet:

  • full container orchestration
  • Kubernetes integration
  • distributed builds
  • advanced secrets management
  • full policy engine
  • multi-tenant billing/accounting
  • browser IDE
  • package cache optimization
  • full audit/event streaming
  • sophisticated sandbox hardening beyond basic user isolation
  • code intelligence or indexing engine

6. Architecture

6.1 Components

Local Controller

Responsible for:

  • SSH connection management
  • bootstrap/install
  • forwarding
  • OpenRPC client
  • node registry

Remote Agent / Server

Responsible for:

  • executing management actions locally on node
  • filesystem operations
  • user/workspace lifecycle
  • reporting state

Workspace

A directory structure representing an isolated development environment.

Sandbox

Logical isolation boundary attached to a workspace.

7. Basic Flow

7.1 Register / prepare node

  1. Operator provides SSH target and credentials.
  2. Controller connects over SSH.
  3. Controller checks prerequisites.
  4. Controller installs or updates CodeSmith server.
  5. Controller starts server.
  6. Controller establishes local forwarding.
  7. Node becomes addressable as a local OpenRPC endpoint.

7.2 Create workspace

  1. Controller calls remote OpenRPC method.
  2. Remote server creates user if needed.
  3. Remote server creates workspace directory.
  4. Remote server sets ownership and permissions.
  5. Remote server returns workspace metadata.

7.3 Use workspace

Later tools or agents connect through the controller to the node and operate only inside that workspace context.

8. Security Model (Minimal)

8.1 Trust boundaries

  • local controller is trusted by the operator
  • SSH is the trusted transport
  • remote CodeSmith server is trusted only after bootstrap
  • workspaces should not run as root

8.2 Privilege model

  • bootstrap may require root or sudo
  • steady-state operations should run with reduced privileges
  • user/workspace actions should be explicit and auditable

8.3 Isolation baseline

Each workspace should at minimum have:

  • dedicated owner user or dedicated group strategy
  • dedicated directory
  • restricted file permissions
  • optional shell/profile restrictions

9. Minimal Remote API Surface (OpenRPC)

Suggested first methods:

Node / service

  • node.info
  • node.health
  • node.version

User management

  • user.create
  • user.get
  • user.list
  • user.delete

Workspace management

  • workspace.create
  • workspace.get
  • workspace.list
  • workspace.delete

Sandbox / environment

  • sandbox.create
  • sandbox.get
  • sandbox.delete

Code / repository setup

  • `repo.init
use skill /hero_crates_best_practices_check put a readme in each of the folders organize the repo well initial start ``` ./crates/codesmith_ui ./crates/codesmith_lib ./crates/codesmiths_server ./crates/codesmith_ssh ./crates/codesmith ``` put a spec document in each directory (SPECIFICATIONS.md) Here is a **minimal spec** for **CodeSmith**. # CodeSmith — Minimal Specification ## 1. Purpose **CodeSmith** is a remote development orchestration module that prepares and manages secure development environments on remote servers over **SSH**. Its first goal is simple: * connect to remote machines over SSH * install and run a small **CodeSmith server** on each machine * expose that server locally through **SSH forwarding** to a local socket * treat each forwarded local socket as a controllable remote development node * let the node create and manage isolated development users and workspaces This is only the skeleton for further work. --- ## 2. High-Level Concept CodeSmith consists of two parts: ### 2.1 Local controller Runs on the operator/developer machine. Responsibilities: * connect to remote nodes over SSH * bootstrap the remote CodeSmith server * maintain SSH tunnels / port forwards / socket forwards * expose each remote node as a **local endpoint** * talk to the remote server over **OpenRPC** * orchestrate multiple nodes uniformly ### 2.2 Remote CodeSmith server Runs on each managed server. Responsibilities: * expose an **OpenRPC API** * create and manage system users for secure development * create and manage isolated workspaces / sandboxes * organize code checkout / initialization * provide basic lifecycle operations for development environments * operate with least privilege where possible --- ## 3. Core Design Principles ### 3.1 SSH-first No public service exposure is required initially. All communication happens through: * SSH for bootstrap and transport * local forwarded socket for API access ### 3.2 OpenRPC-native All remote operations are exposed through a clear OpenRPC interface. This allows: * strong typing * code generation * compatibility with internal tooling * later extension to agents and automation ### 3.3 Secure-by-default Development happens in isolated contexts. Initial security model: * one or more dedicated users per workspace or task * no direct use of root except where unavoidable during setup * clear separation between controller identity and sandbox identity * filesystem and process isolation boundaries defined early ### 3.4 Workspace-oriented The primary unit of work is a **workspace**. A workspace contains: * code * configuration * user context * sandbox/runtime information * metadata needed for AI-assisted development --- ## 4. Initial Scope The first version only needs to support: ### 4.1 Node preparation Prepare a target server over SSH so it can run CodeSmith. Includes: * checking OS compatibility * installing required dependencies * creating required directories * installing or updating the CodeSmith server binary/service * configuring service startup * preparing permissions ### 4.2 Remote server startup Ensure the CodeSmith server is running on the node. Includes: * start * stop * restart * health check * version check ### 4.3 Local forwarding Forward the remote CodeSmith API endpoint to a local socket. Examples: * local Unix socket * local localhost TCP port The controller should maintain a mapping such as: * local socket A -> remote node 1 * local socket B -> remote node 2 ### 4.4 User management Remote server can: * create development users * inspect users created by CodeSmith * delete or disable development users * enforce ownership and permissions for workspaces ### 4.5 Workspace management Remote server can: * create workspace * list workspaces * open existing workspace * delete workspace * assign workspace to a user * initialize directory structure ### 4.6 Sandbox skeleton Remote server can create a minimal isolated execution context. At this stage, sandbox may simply mean: * dedicated Unix user * dedicated workspace directory * restricted permissions * optional process isolation to be added later --- ## 5. Non-Goals for the First Skeleton Not required yet: * full container orchestration * Kubernetes integration * distributed builds * advanced secrets management * full policy engine * multi-tenant billing/accounting * browser IDE * package cache optimization * full audit/event streaming * sophisticated sandbox hardening beyond basic user isolation * code intelligence or indexing engine --- ## 6. Architecture ## 6.1 Components ### Local Controller Responsible for: * SSH connection management * bootstrap/install * forwarding * OpenRPC client * node registry ### Remote Agent / Server Responsible for: * executing management actions locally on node * filesystem operations * user/workspace lifecycle * reporting state ### Workspace A directory structure representing an isolated development environment. ### Sandbox Logical isolation boundary attached to a workspace. --- ## 7. Basic Flow ### 7.1 Register / prepare node 1. Operator provides SSH target and credentials. 2. Controller connects over SSH. 3. Controller checks prerequisites. 4. Controller installs or updates CodeSmith server. 5. Controller starts server. 6. Controller establishes local forwarding. 7. Node becomes addressable as a local OpenRPC endpoint. ### 7.2 Create workspace 1. Controller calls remote OpenRPC method. 2. Remote server creates user if needed. 3. Remote server creates workspace directory. 4. Remote server sets ownership and permissions. 5. Remote server returns workspace metadata. ### 7.3 Use workspace Later tools or agents connect through the controller to the node and operate only inside that workspace context. --- ## 8. Security Model (Minimal) ### 8.1 Trust boundaries * local controller is trusted by the operator * SSH is the trusted transport * remote CodeSmith server is trusted only after bootstrap * workspaces should not run as root ### 8.2 Privilege model * bootstrap may require root or sudo * steady-state operations should run with reduced privileges * user/workspace actions should be explicit and auditable ### 8.3 Isolation baseline Each workspace should at minimum have: * dedicated owner user or dedicated group strategy * dedicated directory * restricted file permissions * optional shell/profile restrictions --- ## 9. Minimal Remote API Surface (OpenRPC) Suggested first methods: ### Node / service * `node.info` * `node.health` * `node.version` ### User management * `user.create` * `user.get` * `user.list` * `user.delete` ### Workspace management * `workspace.create` * `workspace.get` * `workspace.list` * `workspace.delete` ### Sandbox / environment * `sandbox.create` * `sandbox.get` * `sandbox.delete` ### Code / repository setup * `repo.init
despiegk commented 2026-03-10 06:46:50 +00:00
Author
Owner
Copy link

Implementation Specification: Repo Reorganization for hero_codesmith

Objective

Reorganize the hero_codesmith repository from a single-crate structure into a proper multi-crate workspace following the hero_crates_best_practices_check skill. The repo needs to:

  1. Create a crates/ directory with the standardized workspace structure
  2. Add SPECIFICATIONS.md to each crate
  3. Add README.md to each crate
  4. Follow naming conventions (fix issue's codesmiths_server to codesmith_server)
  5. Use the repo name prefix hero_codesmith per naming conventions

Requirements

  • Create a workspace Cargo.toml at root
  • Create 5 crates following the skill structure:
    • hero_codesmith_ui - Admin UI (Axum-based)
    • hero_codesmith_lib - Shared library code (from existing src/devsmith_lib)
    • hero_codesmith_server - Business logic + OpenRPC API (fixed naming from issue's codesmiths)
    • hero_codesmith_ssh - SSH-related functionality (as specified in issue)
    • hero_codesmith - CLI binary (optional)
  • Add hero_codesmith_examples crate for integration tests and examples
  • Add SPECIFICATIONS.md to each crate
  • Add README.md to each crate
  • Maintain existing functionality during migration
  • Follow Unix Domain Socket architecture (no TCP)

Step-by-Step Implementation Plan

Step 1: Create workspace root Cargo.toml

Replace existing Cargo.toml with workspace configuration containing all crate members.

Step 2: Create hero_codesmith_lib crate

Create shared library crate, move code from src/devsmith_lib to crates/hero_codesmith_lib/

Step 3: Create hero_codesmith_server crate

Create server crate with OpenRPC API and Unix Domain Socket binding.

Step 4: Create hero_codesmith_sdk crate

Create SDK crate using openrpc_client! macro from server's openrpc.json.

Step 5: Create hero_codesmith_ui crate

Create UI crate with Axum and openrpc_proxy! macro.

Step 6: Create hero_codesmith_ssh crate

Create SSH functionality crate.

Step 7: Create hero_codesmith (CLI) crate

Create CLI binary crate.

Step 8: Create hero_codesmith_examples crate

Create examples and integration tests crate.

Step 9: Update buildenv.sh and Makefile

Update build configuration for workspace.

Step 10: Update root README.md

Document new workspace structure.

Step 11: Clean up old src/ directory

Remove old single-crate structure.

Step 12: Run validation checks

Verify workspace builds and follows best practices.

Acceptance Criteria

  • Workspace Cargo.toml exists with all 7 crates as members
  • hero_codesmith_lib crate exists with shared code from src/devsmith_lib
  • hero_codesmith_server crate exists with OpenRPC API and Unix socket
  • openrpc.json exists in server crate and is valid
  • hero_codesmith_sdk crate exists with openrpc_client! macro
  • hero_codesmith_ui crate exists with openrpc_proxy! macro
  • hero_codesmith_ssh crate exists with SSH functionality
  • hero_codesmith (CLI) crate exists with main binary
  • hero_codesmith_examples crate exists with examples and integration tests
  • Each crate has SPECIFICATIONS.md
  • Each crate has README.md
  • Each crate has Makefile with build/check/test/clippy/install targets
  • buildenv.sh updated with PROJECT_NAME="hero_codesmith"
  • Root Makefile works with workspace
  • Old src/ directory removed
  • cargo check passes
  • cargo build passes for all crates

Notes

  • Naming Convention Fix: The issue specified codesmiths_server (with 's') which violates the naming convention. This has been corrected to codesmith_server.
  • Repo Name Prefix: Using hero_codesmith as the prefix per naming_convention skill.
  • Socket Architecture: All services bind to Unix Domain Sockets only, no TCP.
# Implementation Specification: Repo Reorganization for hero_codesmith ## Objective Reorganize the hero_codesmith repository from a single-crate structure into a proper multi-crate workspace following the hero_crates_best_practices_check skill. The repo needs to: 1. Create a `crates/` directory with the standardized workspace structure 2. Add SPECIFICATIONS.md to each crate 3. Add README.md to each crate 4. Follow naming conventions (fix issue's `codesmiths_server` to `codesmith_server`) 5. Use the repo name prefix `hero_codesmith` per naming conventions ## Requirements - Create a workspace Cargo.toml at root - Create 5 crates following the skill structure: - `hero_codesmith_ui` - Admin UI (Axum-based) - `hero_codesmith_lib` - Shared library code (from existing src/devsmith_lib) - `hero_codesmith_server` - Business logic + OpenRPC API (fixed naming from issue's codesmiths) - `hero_codesmith_ssh` - SSH-related functionality (as specified in issue) - `hero_codesmith` - CLI binary (optional) - Add `hero_codesmith_examples` crate for integration tests and examples - Add SPECIFICATIONS.md to each crate - Add README.md to each crate - Maintain existing functionality during migration - Follow Unix Domain Socket architecture (no TCP) ## Step-by-Step Implementation Plan ### Step 1: Create workspace root Cargo.toml Replace existing Cargo.toml with workspace configuration containing all crate members. ### Step 2: Create hero_codesmith_lib crate Create shared library crate, move code from src/devsmith_lib to crates/hero_codesmith_lib/ ### Step 3: Create hero_codesmith_server crate Create server crate with OpenRPC API and Unix Domain Socket binding. ### Step 4: Create hero_codesmith_sdk crate Create SDK crate using openrpc_client! macro from server's openrpc.json. ### Step 5: Create hero_codesmith_ui crate Create UI crate with Axum and openrpc_proxy! macro. ### Step 6: Create hero_codesmith_ssh crate Create SSH functionality crate. ### Step 7: Create hero_codesmith (CLI) crate Create CLI binary crate. ### Step 8: Create hero_codesmith_examples crate Create examples and integration tests crate. ### Step 9: Update buildenv.sh and Makefile Update build configuration for workspace. ### Step 10: Update root README.md Document new workspace structure. ### Step 11: Clean up old src/ directory Remove old single-crate structure. ### Step 12: Run validation checks Verify workspace builds and follows best practices. ## Acceptance Criteria - [ ] Workspace Cargo.toml exists with all 7 crates as members - [ ] hero_codesmith_lib crate exists with shared code from src/devsmith_lib - [ ] hero_codesmith_server crate exists with OpenRPC API and Unix socket - [ ] openrpc.json exists in server crate and is valid - [ ] hero_codesmith_sdk crate exists with openrpc_client! macro - [ ] hero_codesmith_ui crate exists with openrpc_proxy! macro - [ ] hero_codesmith_ssh crate exists with SSH functionality - [ ] hero_codesmith (CLI) crate exists with main binary - [ ] hero_codesmith_examples crate exists with examples and integration tests - [ ] Each crate has SPECIFICATIONS.md - [ ] Each crate has README.md - [ ] Each crate has Makefile with build/check/test/clippy/install targets - [ ] buildenv.sh updated with PROJECT_NAME="hero_codesmith" - [ ] Root Makefile works with workspace - [ ] Old src/ directory removed - [ ] cargo check passes - [ ] cargo build passes for all crates ## Notes - **Naming Convention Fix**: The issue specified `codesmiths_server` (with 's') which violates the naming convention. This has been corrected to `codesmith_server`. - **Repo Name Prefix**: Using `hero_codesmith` as the prefix per naming_convention skill. - **Socket Architecture**: All services bind to Unix Domain Sockets only, no TCP.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
development
development_kristof
main
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
lhumina_code/hero_codesmith#5
No description provided.