Release v0.9.0: new language/tool detection and doctor checks

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: mrfandu1

.gitignore

@@ -26,3 +26,6 @@ SECURITY-AUDIT*.md
 /security-notes/
 /audit/
 /threat-model/
+
+# Local Claude Code settings
+.claude/settings.local.json

CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 0.9.0
+
+- Added Rust project support: `Cargo.toml` is detected as a project language and
+  adds Cargo commands (`cargo run`, `cargo build`, `cargo test`, `cargo check`)
+  to the command list. The passport requirements section now lists the Rust
+  toolchain for Rust projects.
+- Added Makefile target detection: top-level targets in `Makefile`, `makefile`,
+  or `GNUmakefile` (up to 20, skipping pattern rules and variable assignments)
+  appear as runnable `make <target>` commands in a Makefile group.
+- Added PHP support: `composer.json` is detected as a project language and adds
+  `composer install` plus each composer script as a runnable command; Laravel
+  projects with an `artisan` file also get `php artisan serve` on port 8000.
+- Added Ruby support: a `Gemfile` is detected as a project language and adds
+  `bundle install`; Rails projects get `rails server` / `rails db:migrate`
+  (port 3000) and RSpec projects get `bundle exec rspec`.
+- Added Justfile recipe detection: recipes in `justfile`, `Justfile`, or
+  `.justfile` appear as runnable `just <recipe>` commands.
+- Added Taskfile detection: tasks in `Taskfile.yml`/`Taskfile.yaml` (go-task)
+  appear as runnable `task <name>` commands.
+- Added Deno task detection: tasks in `deno.json`/`deno.jsonc` appear as
+  runnable `deno task <name>` commands.
+- Added Dockerfile detection: a root `Dockerfile` adds a
+  `docker build -t <project> .` command even without a compose file.
+- Added doctor check: warns when the running Node major version differs from
+  the version pinned in `.nvmrc` or `.node-version`.
+- Added doctor check: warns when multiple package-manager lockfiles coexist
+  (npm/yarn/pnpm/bun), which causes dependency drift.
+- Added doctor check: errors when a local `.env` exists in a git repo but
+  `.gitignore` does not cover it, since secrets could be committed.
+- Added doctor check: info notice when no CI configuration (GitHub Actions,
+  GitLab CI, CircleCI, Azure Pipelines, Jenkins) is found in a git repo.
+- Added `devsurface ports`: a quick terminal view of every project port, who is
+  using busy ones, and a free alternative to try.
+- Added `devsurface scan --json`: prints the full scan result as JSON for
+  scripts and CI (the update notice is suppressed so output stays parseable).
+- Busy ports now carry a suggested free port. The Ports views in the dashboard
+  and the doctor warning show "in use by X — try 5174" instead of just "in use".
+- Added git hook tooling detection: `.pre-commit-config.yaml` and
+  `lefthook.yml` add install/run commands to the dashboard command list.
+- Added doctor check: warns when package.json's `packageManager` field
+  disagrees with the lockfile that is actually committed.
+- Added doctor notice: points out when the project ships a dev container as a
+  one-click setup path.
+- `cargo run` is now only offered when the crate has a runnable binary
+  (`src/main.rs` or a `[[bin]]` section), so library-only crates and virtual
+  workspaces no longer show a command that would fail.
+
 ## 0.8.0
 
 - Added Project Passport: `devsurface passport` generates a single self-contained

README.md

@@ -41,7 +41,8 @@
 
 DevSurface is a zero-config CLI and local browser dashboard for understanding,
 configuring, and running unfamiliar repositories. It detects Node.js package scripts,
-Python, Go, and Java project commands, environment files, occupied ports, Docker
+Python, Go, Java, Rust, PHP, and Ruby project commands, Makefile / Justfile /
+Taskfile / Deno tasks, environment files, occupied ports, Docker
 Compose services, frameworks, live command logs, repo health checks, and
 multi-workspace projects.
 
@@ -155,7 +156,8 @@ Run DevSurface without installing it globally:
 | Command                            | Description                                                          |
 | ---------------------------------- | -------------------------------------------------------------------- |
 | `devsurface`                       | Scan the current project, start the dashboard, and open the browser. |
-| `devsurface scan`                  | Print detected project information to the terminal.                  |
+| `devsurface scan`                  | Print detected project information (`--json` for machine output).    |
+| `devsurface ports`                 | Show project ports, what is using them, and free alternatives.       |
 | `devsurface doctor`                | Print setup and repo health warnings.                                |
 | `devsurface init`                  | Create a starter `devsurface.config.json`.                           |
 | `devsurface passport`              | Generate a shareable HTML onboarding report (Project Passport).      |

opencode.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "viktor": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Viktor",
+      "options": {
+        "baseURL": "http://127.0.0.1:6061/v1",
+        "apiKey": "viktor"
+      },
+      "models": {
+        "viktor": {
+          "name": "Viktor"
+        }
+      }
+    }
+  }
+}

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "devsurface",
-  "version": "0.8.0",
-  "description": "Zero-config local developer dashboard and CLI for Node.js, Python, Go, and Java repositories. Detect scripts, env files, ports, Docker services, frameworks, logs, and repo health.",
+  "version": "0.9.0",
+  "description": "Zero-config local developer dashboard and CLI for Node.js, Python, Go, Java, and Rust repositories. Detect scripts, env files, ports, Docker services, frameworks, logs, and repo health.",
   "type": "module",
   "license": "MIT",
   "author": "mrfandu1",

package.json

@@ -0,0 +1,29 @@
+import pc from 'picocolors';
+import { scanProject } from '../../core/scanner/index.js';
+import { safeTerminalText } from '../terminal.js';
+
+export async function portsCommand(cwd = process.cwd()): Promise<void> {
+  const scan = await scanProject(cwd);
+
+  if (scan.ports.length === 0) {
+    console.log('No configured or inferred ports for this project.');
+    return;
+  }
+
+  for (const port of scan.ports) {
+    if (!port.inUse) {
+      console.log(`${pc.green('free')}    ${port.port}  http://localhost:${port.port}`);
+      continue;
+    }
+
+    const owner =
+      port.owner == null
+        ? 'unknown process'
+        : port.owner.name === null
+          ? `PID ${port.owner.pid}`
+          : `${safeTerminalText(port.owner.name)} (PID ${port.owner.pid})`;
+    const suggestion =
+      typeof port.suggestedFreePort === 'number' ? ` — try ${port.suggestedFreePort}` : '';
+    console.log(`${pc.red('in use')}  ${port.port}  by ${owner}${suggestion}`);
+  }
+}

src/cli/commands/ports.ts

@@ -34,6 +34,14 @@ export function printScanResult(scan: ScanResult): void {
   }
 }
 
-export async function scanCommand(cwd = process.cwd()): Promise<void> {
-  printScanResult(await scanProject(cwd));
+export async function scanCommand(
+  cwd = process.cwd(),
+  options: { json?: boolean } = {}
+): Promise<void> {
+  const scan = await scanProject(cwd);
+  if (options.json === true) {
+    console.log(JSON.stringify(scan, null, 2));
+    return;
+  }
+  printScanResult(scan);
 }

src/cli/commands/scan.ts

@@ -4,6 +4,7 @@ import { doctorCommand } from './commands/doctor.js';
 import { initCommand } from './commands/init.js';
 import { onboardCommand } from './commands/onboard.js';
 import { passportCommand } from './commands/passport.js';
+import { portsCommand } from './commands/ports.js';
 import { runCommand } from './commands/run.js';
 import { scanCommand } from './commands/scan.js';
 import { startCommand } from './commands/start.js';
@@ -27,10 +28,12 @@ function toPort(value: string): number {
   return port;
 }
 
-function handle(command: Promise<void>): void {
+function handle(command: Promise<void>, options: { updateNotice?: boolean } = {}): void {
   command
     .then(async () => {
-      await printUpdateNotice(DEV_SURFACE_VERSION);
+      if (options.updateNotice !== false) {
+        await printUpdateNotice(DEV_SURFACE_VERSION);
+      }
     })
     .catch((error) => {
       const message = error instanceof Error ? error.message : String(error);
@@ -98,8 +101,19 @@ workspace
 program
   .command('scan')
   .description('Print detected project info.')
+  .option('--json', 'print the full scan result as JSON')
+  .action((options: { json?: boolean }) => {
+    // JSON output must stay machine-parseable, so skip the update notice.
+    handle(scanCommand(process.cwd(), { json: options.json }), {
+      updateNotice: options.json !== true
+    });
+  });
+
+program
+  .command('ports')
+  .description('Show project ports, what is using them, and free alternatives.')
   .action(() => {
-    handle(scanCommand(process.cwd()));
+    handle(portsCommand(process.cwd()));
   });
 
 program

src/cli/index.ts

@@ -129,12 +129,22 @@ export async function runDoctor(root = process.cwd(), scan?: ScanResult): Promis
   }
 
   for (const port of result.ports.filter((probe) => probe.inUse)) {
+    const owner =
+      port.owner == null
+        ? 'Something'
+        : port.owner.name === null
+          ? `PID ${port.owner.pid}`
+          : `${port.owner.name} (PID ${port.owner.pid})`;
+    const suggestion =
+      typeof port.suggestedFreePort === 'number'
+        ? ` Port ${port.suggestedFreePort} is free — try that instead.`
+        : '';
     warnings.push(
       warning(
         `port-${port.port}-in-use`,
         'error',
         `Port ${port.port} is already in use`,
-        `Something is already bound to 127.0.0.1:${port.port}.`
+        `${owner} is already bound to 127.0.0.1:${port.port}.${suggestion}`
       )
     );
   }
@@ -172,5 +182,123 @@ export async function runDoctor(root = process.cwd(), scan?: ScanResult): Promis
     );
   }
 
+  // Pinned Node version vs the Node actually running devsurface.
+  if (isNodeProject) {
+    const pinned =
+      (await readIfPresent(path.join(root, '.nvmrc'))) ??
+      (await readIfPresent(path.join(root, '.node-version')));
+    const pinnedMajor = pinned === null ? null : /^v?(\d+)/.exec(pinned.trim())?.[1];
+    const runningMajor = /^v?(\d+)/.exec(process.version)?.[1];
+    if (pinnedMajor !== undefined && pinnedMajor !== null && pinnedMajor !== runningMajor) {
+      warnings.push(
+        warning(
+          'node-version-mismatch',
+          'warning',
+          'Node version differs from the pinned version',
+          `This project pins Node ${pinned?.trim()} but Node ${process.version} is running. Switch versions (for example with nvm or fnm) before installing or running.`
+        )
+      );
+    }
+  }
+
+  // Multiple package-manager lockfiles usually mean contributors used different tools.
+  const lockfiles = ['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lockb', 'bun.lock'];
+  const presentLockfiles: string[] = [];
+  for (const lockfile of lockfiles) {
+    if (await pathExists(path.join(root, lockfile))) {
+      presentLockfiles.push(lockfile);
+    }
+  }
+  if (presentLockfiles.length > 1) {
+    warnings.push(
+      warning(
+        'multiple-lockfiles',
+        'warning',
+        'Multiple lockfiles found',
+        `Found ${presentLockfiles.join(', ')}. Keep only the lockfile for the package manager this project uses to avoid dependency drift.`
+      )
+    );
+  }
+
+  // A local .env that .gitignore does not cover is one commit away from leaking secrets.
+  if (result.env?.hasLocal && (await pathExists(path.join(root, '.git')))) {
+    const gitignore = (await readIfPresent(path.join(root, '.gitignore'))) ?? '';
+    const coversEnv = gitignore
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .some((line) => line === '.env' || line === '.env*' || line === '*.env' || line === '/.env');
+    if (!coversEnv) {
+      warnings.push(
+        warning(
+          'env-not-gitignored',
+          'error',
+          '.env is not listed in .gitignore',
+          'A local .env exists but .gitignore does not cover it, so secrets could be committed. Add ".env" to .gitignore.'
+        )
+      );
+    }
+  }
+
+  // A pinned packageManager field that disagrees with the detected lockfile confuses installs.
+  const pinnedManager = result.packageJson?.data.packageManager?.split('@')[0]?.trim();
+  if (
+    pinnedManager !== undefined &&
+    pinnedManager.length > 0 &&
+    result.packageManager !== null &&
+    pinnedManager !== result.packageManager
+  ) {
+    warnings.push(
+      warning(
+        'package-manager-mismatch',
+        'warning',
+        'Package manager mismatch',
+        `package.json pins "${pinnedManager}" via the packageManager field, but the lockfile belongs to ${result.packageManager}. Use ${pinnedManager} so installs match the lockfile the project expects.`
+      )
+    );
+  }
+
+  // Dev containers are a one-click setup path worth pointing out.
+  if (
+    (await pathExists(path.join(root, '.devcontainer', 'devcontainer.json'))) ||
+    (await pathExists(path.join(root, '.devcontainer.json')))
+  ) {
+    warnings.push(
+      warning(
+        'devcontainer-available',
+        'info',
+        'Dev container available',
+        'This project ships a dev container. Opening it in VS Code ("Reopen in Container") or GitHub Codespaces gives a ready-made environment.'
+      )
+    );
+  }
+
+  // Repos without any CI config get a gentle nudge, not an error.
+  if (await pathExists(path.join(root, '.git'))) {
+    const ciMarkers = [
+      path.join('.github', 'workflows'),
+      '.gitlab-ci.yml',
+      path.join('.circleci', 'config.yml'),
+      'azure-pipelines.yml',
+      'Jenkinsfile'
+    ];
+    let hasCi = false;
+    for (const marker of ciMarkers) {
+      if (await pathExists(path.join(root, marker))) {
+        hasCi = true;
+        break;
+      }
+    }
+    if (!hasCi) {
+      warnings.push(
+        warning(
+          'no-ci-config',
+          'info',
+          'No CI configuration detected',
+          'No GitHub Actions, GitLab CI, CircleCI, Azure Pipelines, or Jenkins config was found. Automated checks catch broken builds before review.'
+        )
+      );
+    }
+  }
+
   return warnings;
 }