@neurocode-ai/web 1.18.8

package/src/content/docs/it/rules.mdx

@@ -0,0 +1,180 @@
+---
+title: Regole
+description: Imposta istruzioni personalizzate per opencode.
+---
+
+Puoi fornire istruzioni personalizzate a opencode creando un file `AGENTS.md`. E' simile alle regole di Cursor. Contiene istruzioni che verranno incluse nel contesto dell'LLM per personalizzarne il comportamento per il tuo progetto.
+
+---
+
+## Inizializza
+
+Per creare un nuovo file `AGENTS.md`, puoi eseguire il comando `/init` in opencode.
+
+:::tip
+Dovresti committare il file `AGENTS.md` del progetto in Git.
+:::
+
+Questo scansiona il progetto e tutti i suoi contenuti per capire di cosa si tratta e generare un file `AGENTS.md`. Questo aiuta opencode a orientarsi meglio nel progetto.
+
+Se hai gia' un file `AGENTS.md` esistente, cerchera' di aggiungervi contenuti.
+
+---
+
+## Esempio
+
+Puoi anche creare questo file manualmente. Ecco un esempio di alcune cose che puoi inserire in un file `AGENTS.md`.
+
+```markdown title="AGENTS.md"
+# SST v3 Monorepo Project
+
+This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management.
+
+## Project Structure
+
+- `packages/` - Contains all workspace packages (functions, core, web, etc.)
+- `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts)
+- `sst.config.ts` - Main SST configuration with dynamic imports
+
+## Code Standards
+
+- Use TypeScript with strict mode enabled
+- Shared code goes in `packages/core/` with proper exports configuration
+- Functions go in `packages/functions/`
+- Infrastructure should be split into logical files in `infra/`
+
+## Monorepo Conventions
+
+- Import shared modules using workspace names: `@my-app/core/example`
+```
+
+Qui stiamo aggiungendo istruzioni specifiche del progetto e saranno condivise con il tuo team.
+
+---
+
+## Tipi
+
+opencode supporta anche la lettura del file `AGENTS.md` da piu' posizioni, e questo serve a scopi diversi.
+
+### Progetto
+
+Metti un `AGENTS.md` nella root del progetto per regole specifiche del progetto. Si applicano solo quando stai lavorando in questa directory o nelle sue sottodirectory.
+
+### Globale
+
+Puoi anche avere regole globali in un file `~/.config/opencode/AGENTS.md`. Queste si applicano a tutte le sessioni di opencode.
+
+Dato che questo non viene committato in Git o condiviso con il team, consigliamo di usarlo per specificare regole personali che l'LLM deve seguire.
+
+### Compatibilita Claude Code
+
+Per gli utenti che migrano da Claude Code, OpenCode supporta come fallback le convenzioni di file di Claude Code:
+
+- **Regole di progetto**: `CLAUDE.md` nella directory del progetto (usato se non esiste `AGENTS.md`)
+- **Regole globali**: `~/.claude/CLAUDE.md` (usato se non esiste `~/.config/opencode/AGENTS.md`)
+- **Skill**: `~/.claude/skills/` — vedi [Skill agente](/docs/skills/) per i dettagli
+
+Per disabilitare la compatibilita' con Claude Code, imposta una di queste variabili d'ambiente:
+
+```bash
+export OPENCODE_DISABLE_CLAUDE_CODE=1        # Disable all .claude support
+export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 # Disable only ~/.claude/CLAUDE.md
+export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills
+```
+
+---
+
+## Priorita
+
+Quando opencode si avvia, cerca i file di regole in questo ordine:
+
+1. **File locali** risalendo dalla directory corrente (`AGENTS.md`, `CLAUDE.md`)
+2. **File globale** in `~/.config/opencode/AGENTS.md`
+3. **File Claude Code** in `~/.claude/CLAUDE.md` (se non disabilitato)
+
+In ogni categoria vince il primo file corrispondente. Per esempio, se hai sia `AGENTS.md` sia `CLAUDE.md`, viene usato solo `AGENTS.md`. Allo stesso modo, `~/.config/opencode/AGENTS.md` ha priorita' su `~/.claude/CLAUDE.md`.
+
+---
+
+## Istruzioni personalizzate
+
+Puoi specificare file di istruzioni personalizzati nel tuo `opencode.json` o nel globale `~/.config/opencode/opencode.json`. Questo permette a te e al tuo team di riusare regole esistenti invece di doverle duplicare in AGENTS.md.
+
+Esempio:
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
+}
+```
+
+Puoi anche usare URL remoti per caricare istruzioni dal web.
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": ["https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"]
+}
+```
+
+Le istruzioni remote vengono recuperate con un timeout di 5 secondi.
+
+Tutti i file di istruzioni vengono combinati con i tuoi file `AGENTS.md`.
+
+---
+
+## Riferisci file esterni
+
+Anche se opencode non interpreta automaticamente i riferimenti a file in `AGENTS.md`, puoi ottenere una funzionalita' simile in due modi:
+
+### Usa opencode.json
+
+L'approccio consigliato e' usare il campo `instructions` in `opencode.json`:
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": ["docs/development-standards.md", "test/testing-guidelines.md", "packages/*/AGENTS.md"]
+}
+```
+
+### Istruzioni manuali in AGENTS.md
+
+Puoi insegnare a opencode a leggere file esterni fornendo istruzioni esplicite nel tuo `AGENTS.md`. Ecco un esempio pratico:
+
+```markdown title="AGENTS.md"
+# TypeScript Project Rules
+
+## External File Loading
+
+CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand.
+
+Instructions:
+
+- Do NOT preemptively load all references - use lazy loading based on actual need
+- When loaded, treat content as mandatory instructions that override defaults
+- Follow references recursively when needed
+
+## Development Guidelines
+
+For TypeScript code style and best practices: @docs/typescript-guidelines.md
+For React component architecture and hooks patterns: @docs/react-patterns.md
+For REST API design and error handling: @docs/api-standards.md
+For testing strategies and coverage requirements: @test/testing-guidelines.md
+
+## General Guidelines
+
+Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md.
+```
+
+Questo approccio ti permette di:
+
+- Crea file di regole modulari e riutilizzabili
+- Condividi regole tra progetti con symlink o submodule Git
+- Mantieni AGENTS.md conciso riferendoti a linee guida dettagliate
+- Assicurati che opencode carichi file solo quando servono per il task specifico
+
+:::tip
+Per monorepo o progetti con standard condivisi, usare `opencode.json` con pattern glob (come `packages/*/AGENTS.md`) e' piu' manutenibile rispetto alle istruzioni manuali.
+:::

package/src/content/docs/it/sdk.mdx

@@ -0,0 +1,463 @@
+---
+title: SDK
+description: Client JS type-safe per il server opencode.
+---
+
+import config from "../../../../config.mjs"
+export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts`
+
+L'SDK JS/TS di opencode fornisce un client type-safe per interagire con il server.
+Usalo per creare integrazioni e controllare opencode in modo programmatico.
+
+[Scopri di piu](/docs/server) su come funziona il server. Per esempi, guarda i [progetti](/docs/ecosystem#projects) creati dalla comunita.
+
+---
+
+## Installa
+
+Installa l'SDK da npm:
+
+```bash
+npm install @opencode-ai/sdk
+```
+
+---
+
+## Crea un client
+
+Crea un'istanza di opencode:
+
+```javascript
+import { createOpencode } from "@opencode-ai/sdk"
+
+const { client } = await createOpencode()
+```
+
+Questo avvia sia un server sia un client
+
+#### Opzioni
+
+| Opzione    | Tipo          | Descrizione                    | Predefinito |
+| ---------- | ------------- | ------------------------------ | ----------- |
+| `hostname` | `string`      | Hostname del server            | `127.0.0.1` |
+| `port`     | `number`      | Porta del server               | `4096`      |
+| `signal`   | `AbortSignal` | Segnale di abort per annullare | `undefined` |
+| `timeout`  | `number`      | Timeout in ms per avvio server | `5000`      |
+| `config`   | `Config`      | Oggetto di configurazione      | `{}`        |
+
+---
+
+## Configurazione
+
+Puoi passare un oggetto di configurazione per personalizzare il comportamento. L'istanza legge comunque `opencode.json`, ma puoi sovrascrivere o aggiungere configurazione inline:
+
+```javascript
+import { createOpencode } from "@opencode-ai/sdk"
+
+const opencode = await createOpencode({
+  hostname: "127.0.0.1",
+  port: 4096,
+  config: {
+    model: "anthropic/claude-3-5-sonnet-20241022",
+  },
+})
+
+console.log(`Server running at ${opencode.server.url}`)
+
+opencode.server.close()
+```
+
+## Solo client
+
+Se hai gia un'istanza di opencode in esecuzione, puoi creare un client per collegarti:
+
+```javascript
+import { createOpencodeClient } from "@opencode-ai/sdk"
+
+const client = createOpencodeClient({
+  baseUrl: "http://localhost:4096",
+})
+```
+
+#### Opzioni
+
+| Opzione         | Tipo       | Descrizione                         | Predefinito             |
+| --------------- | ---------- | ----------------------------------- | ----------------------- |
+| `baseUrl`       | `string`   | URL del server                      | `http://localhost:4096` |
+| `fetch`         | `function` | Implementazione fetch custom        | `globalThis.fetch`      |
+| `parseAs`       | `string`   | Metodo di parsing della risposta    | `auto`                  |
+| `responseStyle` | `string`   | Stile di ritorno: `data` o `fields` | `fields`                |
+| `throwOnError`  | `boolean`  | Lancia errori invece di restituirli | `false`                 |
+
+---
+
+## Tipi
+
+L'SDK include definizioni TypeScript per tutti i tipi API. Importale direttamente:
+
+```typescript
+import type { Session, Message, Part } from "@opencode-ai/sdk"
+```
+
+Tutti i tipi sono generati dalla specifica OpenAPI del server e disponibili nel <a href={typesUrl}>file dei tipi</a>.
+
+---
+
+## Errori
+
+L'SDK puo lanciare errori che puoi intercettare e gestire:
+
+```typescript
+try {
+  await client.session.get({ path: { id: "invalid-id" } })
+} catch (error) {
+  console.error("Failed to get session:", (error as Error).message)
+}
+```
+
+---
+
+## Output Strutturato
+
+Puoi richiedere un output JSON strutturato dal modello specificando un `format` con uno schema JSON. Il modello usera un tool `StructuredOutput` per restituire JSON validato che corrisponde al tuo schema.
+
+### Uso Base
+
+```typescript
+const result = await client.session.prompt({
+  path: { id: sessionId },
+  body: {
+    parts: [{ type: "text", text: "Research Anthropic and provide company info" }],
+    format: {
+      type: "json_schema",
+      schema: {
+        type: "object",
+        properties: {
+          company: { type: "string", description: "Company name" },
+          founded: { type: "number", description: "Year founded" },
+          products: {
+            type: "array",
+            items: { type: "string" },
+            description: "Main products",
+          },
+        },
+        required: ["company", "founded"],
+      },
+    },
+  },
+})
+
+// Access the structured output
+console.log(result.data.info.structured_output)
+// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }
+```
+
+### Tipi di Formato Output
+
+| Tipo          | Descrizione                                                         |
+| ------------- | ------------------------------------------------------------------- |
+| `text`        | Predefinito. Risposta di testo standard (nessun output strutturato) |
+| `json_schema` | Restituisce JSON validato che corrisponde allo schema fornito       |
+
+### Formato Schema JSON
+
+Quando usi `type: 'json_schema'`, fornisci:
+
+| Campo        | Tipo            | Descrizione                                                           |
+| ------------ | --------------- | --------------------------------------------------------------------- |
+| `type`       | `'json_schema'` | Richiesto. Specifica la modalita schema JSON                          |
+| `schema`     | `object`        | Richiesto. Oggetto JSON Schema che definisce la struttura dell'output |
+| `retryCount` | `number`        | Opzionale. Numero di tentativi di validazione (default: 2)            |
+
+### Gestione Errori
+
+Se il modello non riesce a produrre un output strutturato valido dopo tutti i tentativi, la risposta includera un `StructuredOutputError`:
+
+```typescript
+if (result.data.info.error?.name === "StructuredOutputError") {
+  console.error("Failed to produce structured output:", result.data.info.error.message)
+  console.error("Attempts:", result.data.info.error.retries)
+}
+```
+
+### Best Practices
+
+1. **Fornisci descrizioni chiare** nelle proprieta del tuo schema per aiutare il modello a capire quali dati estrarre
+2. **Usa `required`** per specificare quali campi devono essere presenti
+3. **Mantieni gli schemi focalizzati** - schemi annidati complessi potrebbero essere piu difficili da compilare correttamente per il modello
+4. **Imposta un `retryCount` appropriato** - aumenta per schemi complessi, diminuisci per quelli semplici
+
+---
+
+## API
+
+L'SDK espone tutte le API del server tramite un client type-safe.
+
+---
+
+### Globale
+
+| Metodo            | Descrizione                       | Risposta                             |
+| ----------------- | --------------------------------- | ------------------------------------ |
+| `global.health()` | Controlla stato e versione server | `{ healthy: true, version: string }` |
+
+---
+
+#### Esempi
+
+```javascript
+const health = await client.global.health()
+console.log(health.data.version)
+```
+
+---
+
+### App
+
+| Metodo         | Descrizione             | Risposta                                    |
+| -------------- | ----------------------- | ------------------------------------------- |
+| `app.log()`    | Scrive una voce di log  | `boolean`                                   |
+| `app.agents()` | Elenca tutti gli agenti | <a href={typesUrl}><code>Agent[]</code></a> |
+
+---
+
+#### Esempi
+
+```javascript
+// Write a log entry
+await client.app.log({
+  body: {
+    service: "my-app",
+    level: "info",
+    message: "Operation completed",
+  },
+})
+
+// List available agents
+const agents = await client.app.agents()
+```
+
+---
+
+### Progetto
+
+| Metodo              | Descrizione       | Risposta                                      |
+| ------------------- | ----------------- | --------------------------------------------- |
+| `project.list()`    | Elenca i progetti | <a href={typesUrl}><code>Project[]</code></a> |
+| `project.current()` | Progetto corrente | <a href={typesUrl}><code>Project</code></a>   |
+
+---
+
+#### Esempi
+
+```javascript
+// List all projects
+const projects = await client.project.list()
+
+// Get current project
+const currentProject = await client.project.current()
+```
+
+---
+
+### Path
+
+| Metodo       | Descrizione       | Risposta                                 |
+| ------------ | ----------------- | ---------------------------------------- |
+| `path.get()` | Percorso corrente | <a href={typesUrl}><code>Path</code></a> |
+
+---
+
+#### Esempi
+
+```javascript
+// Get current path information
+const pathInfo = await client.path.get()
+```
+
+---
+
+### Config
+
+| Metodo               | Descrizione                       | Risposta                                                                                              |
+| -------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `config.get()`       | Ottieni info config               | <a href={typesUrl}><code>Config</code></a>                                                            |
+| `config.providers()` | Elenca provider e modelli default | `{ providers: `<a href={typesUrl}><code>Provider[]</code></a>`, default: { [key: string]: string } }` |
+
+---
+
+#### Esempi
+
+```javascript
+const config = await client.config.get()
+
+const { providers, default: defaults } = await client.config.providers()
+```
+
+---
+
+### Sessioni
+
+| Metodo                                                     | Descrizione                       | Note                                                                                                                                                                                                                          |
+| ---------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `session.list()`                                           | Elenca le sessioni                | Returns <a href={typesUrl}><code>Session[]</code></a>                                                                                                                                                                         |
+| `session.get({ path })`                                    | Ottieni una sessione              | Returns <a href={typesUrl}><code>Session</code></a>                                                                                                                                                                           |
+| `session.children({ path })`                               | Elenca sessioni figlie            | Returns <a href={typesUrl}><code>Session[]</code></a>                                                                                                                                                                         |
+| `session.create({ body })`                                 | Crea una sessione                 | Returns <a href={typesUrl}><code>Session</code></a>                                                                                                                                                                           |
+| `session.delete({ path })`                                 | Elimina una sessione              | Returns `boolean`                                                                                                                                                                                                             |
+| `session.update({ path, body })`                           | Aggiorna proprieta della sessione | Returns <a href={typesUrl}><code>Session</code></a>                                                                                                                                                                           |
+| `session.init({ path, body })`                             | Analizza app e crea `AGENTS.md`   | Returns `boolean`                                                                                                                                                                                                             |
+| `session.abort({ path })`                                  | Interrompe una sessione in corso  | Returns `boolean`                                                                                                                                                                                                             |
+| `session.share({ path })`                                  | Condivide la sessione             | Returns <a href={typesUrl}><code>Session</code></a>                                                                                                                                                                           |
+| `session.unshare({ path })`                                | Rimuove la condivisione           | Returns <a href={typesUrl}><code>Session</code></a>                                                                                                                                                                           |
+| `session.summarize({ path, body })`                        | Riassume la sessione              | Returns `boolean`                                                                                                                                                                                                             |
+| `session.messages({ path })`                               | Elenca i messaggi della sessione  | Returns `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}[]`                                                                                                       |
+| `session.message({ path })`                                | Ottieni dettagli di un messaggio  | Returns `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}`                                                                                                         |
+| `session.prompt({ path, body })`                           | Invia un prompt                   | `body.noReply: true` returns UserMessage (solo contesto). Di default ritorna <a href={typesUrl}><code>AssistantMessage</code></a> con risposta AI. Supporta `body.outputFormat` per [output strutturato](#output-strutturato) |
+| `session.command({ path, body })`                          | Invia un comando alla sessione    | Returns `{ info: `<a href={typesUrl}><code>AssistantMessage</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}`                                                                                                |
+| `session.shell({ path, body })`                            | Esegue un comando shell           | Returns <a href={typesUrl}><code>AssistantMessage</code></a>                                                                                                                                                                  |
+| `session.revert({ path, body })`                           | Ripristina un messaggio           | Returns <a href={typesUrl}><code>Session</code></a>                                                                                                                                                                           |
+| `session.unrevert({ path })`                               | Ripristina messaggi revertiti     | Returns <a href={typesUrl}><code>Session</code></a>                                                                                                                                                                           |
+| `postSessionByIdPermissionsByPermissionId({ path, body })` | Risponde a una richiesta permessi | Returns `boolean`                                                                                                                                                                                                             |
+
+---
+
+#### Esempi
+
+```javascript
+// Create and manage sessions
+const session = await client.session.create({
+  body: { title: "My session" },
+})
+
+const sessions = await client.session.list()
+
+// Send a prompt message
+const result = await client.session.prompt({
+  path: { id: session.id },
+  body: {
+    model: { providerID: "anthropic", modelID: "claude-3-5-sonnet-20241022" },
+    parts: [{ type: "text", text: "Hello!" }],
+  },
+})
+
+// Inject context without triggering AI response (useful for plugins)
+await client.session.prompt({
+  path: { id: session.id },
+  body: {
+    noReply: true,
+    parts: [{ type: "text", text: "You are a helpful assistant." }],
+  },
+})
+```
+
+---
+
+### File
+
+| Metodo                    | Descrizione                     | Risposta                                                                                    |
+| ------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------- |
+| `find.text({ query })`    | Cerca testo nei file            | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` |
+| `find.files({ query })`   | Trova file e directory per nome | `string[]` (paths)                                                                          |
+| `find.symbols({ query })` | Trova simboli nel workspace     | <a href={typesUrl}><code>Symbol[]</code></a>                                                |
+| `file.read({ query })`    | Legge un file                   | `{ type: "raw" \| "patch", content: string }`                                               |
+| `file.status({ query? })` | Stato dei file tracciati        | <a href={typesUrl}><code>File[]</code></a>                                                  |
+
+`find.files` supporta alcuni campi query opzionali:
+
+- `type`: `"file"` or `"directory"`
+- `directory`: sovrascrive la root del progetto per la ricerca
+- `limit`: risultati massimi (1–200)
+
+---
+
+#### Esempi
+
+```javascript
+// Search and read files
+const textResults = await client.find.text({
+  query: { pattern: "function.*opencode" },
+})
+
+const files = await client.find.files({
+  query: { query: "*.ts", type: "file" },
+})
+
+const directories = await client.find.files({
+  query: { query: "packages", type: "directory", limit: 20 },
+})
+
+const content = await client.file.read({
+  query: { path: "src/index.ts" },
+})
+```
+
+---
+
+### TUI
+
+| Metodo                         | Descrizione                | Risposta  |
+| ------------------------------ | -------------------------- | --------- |
+| `tui.appendPrompt({ body })`   | Aggiunge testo al prompt   | `boolean` |
+| `tui.openHelp()`               | Apre la finestra help      | `boolean` |
+| `tui.openSessions()`           | Apre il selettore sessioni | `boolean` |
+| `tui.openThemes()`             | Apre il selettore temi     | `boolean` |
+| `tui.openModels()`             | Apre il selettore modelli  | `boolean` |
+| `tui.submitPrompt()`           | Invia il prompt corrente   | `boolean` |
+| `tui.clearPrompt()`            | Pulisce il prompt          | `boolean` |
+| `tui.executeCommand({ body })` | Esegue un comando          | `boolean` |
+| `tui.showToast({ body })`      | Mostra una notifica toast  | `boolean` |
+
+---
+
+#### Esempi
+
+```javascript
+// Control TUI interface
+await client.tui.appendPrompt({
+  body: { text: "Add this to prompt" },
+})
+
+await client.tui.showToast({
+  body: { message: "Task completed", variant: "success" },
+})
+```
+
+---
+
+### Autenticazione
+
+| Metodo              | Descrizione              | Risposta  |
+| ------------------- | ------------------------ | --------- |
+| `auth.set({ ... })` | Imposta credenziali auth | `boolean` |
+
+---
+
+#### Esempi
+
+```javascript
+await client.auth.set({
+  path: { id: "anthropic" },
+  body: { type: "api", key: "your-api-key" },
+})
+```
+
+---
+
+### Eventi
+
+| Metodo              | Descrizione                  | Risposta                     |
+| ------------------- | ---------------------------- | ---------------------------- |
+| `event.subscribe()` | Stream di server-sent events | Stream di server-sent events |
+
+---
+
+#### Esempi
+
+```javascript
+// Listen to real-time events
+const events = await client.event.subscribe()
+for await (const event of events.stream) {
+  console.log("Event:", event.type, event.properties)
+}
+```