Cygnum DEV Editor
Cygnum DEV Editor connects VS Code to the Cygnum DEV environment so you can authenticate, mount remote folders, browse source held on the server, and open UniBasic files directly in the editor. It includes IntelliSense completions, code formatting, and intelligent indentation for UniBasic code.
This is a very early beta!
Usage Instructions
Login
Should just need to do this occasionally.
F1 Cygnum: Login
You will get an error notifcation in the bottom right 'Must sign in with Microsoft to use cygnum-dev-editor API'. Need to sign in from the accounts link (person in a circle) at bottomn of left-hand sidebar. Choose 'Sign in with Microsoft to use Cygnum DEV Editor'.
Source Code Browser
Open the Explorer in left hand window. If something already open then File Close Workspace or File Close Folder.
F1 Cygnum: Connect to Cygnum
Should now show 'Cygnum' root folder. Make take a few seconds to connect. Use the refresh link just above the folder if it doesn't open automatically.
You can also use the Open Item button in the Explorer title bar, or run Cygnum: Open Item, to jump directly to an item. The picker shows suggestions as you type and opens the resolved remote path in the editor and Explorer.
Open 'ufo' folder.
Browse down to open e.g. OUFO then OXX to get source files.
UniBasic language mode is applied when the remote /dev/fs/stat metadata returns contentType: text/x-unibasic. All other files are left to VS Code's normal filename-based language detection.
Terminal
F1 Cygnum: Open Terminal
Runs entered commands in Cygnum.
Local Working Copy (Optional)
This mode opens ordinary local files so Chat, filesystem search, and terminal tools can
work with them. The existing virtual workspace remains available and unchanged.
- Sign in, then run
Cygnum: Download or Refresh Local Working Copy.
- The command downloads the full remote filesystem (
/) to ~/Cygnum-VSCode/working-copy/ and adds that folder to the workspace as Cygnum Local.
- Use Cygnum Local Changes in Explorer to see tracked files whose local bytes differ from the last published version. Click an entry to open it. Use its refresh button to rescan after external tools change files.
- Edit and save locally. Saving does not publish to the server.
- Run
Cygnum: Publish Local File with a downloaded file active, then confirm.
To refresh the working copy, rerun the command. Local changes, dirty editors, and untracked existing files are skipped, not
overwritten. Review the counts and the Cygnum Working Copy output channel for failures.
Downloads run with four workers, support cancellation, and retain completed files.
If the manifest or an API fallback read receives HTTP 429, the download retries up to
three times. It honours Retry-After or the server's JSON retry delay; without either,
it waits 3, 6, then 12 seconds. Cancellation interrupts the wait. If the server continues
to rate-limit requests, the download stops and can be retried later.
All server API requests are queued and executed one at a time, including download
fallbacks and editor features. Only share-file reads can overlap; failed API requests
do not block subsequent queued requests. The queue is shared within one extension host,
not across separate VS Code windows or machines.
The API returns recursive manifest pages targeting 1,000 files. The server may return
slightly more or fewer. The client follows opaque cursors sequentially, persists completed
pages, and can stop between requests if cancelled.
The local hierarchy matches API paths. The server owns all API-to-share mapping and
returns an optional shareRelativePath in each manifest entry. For example,
/ufo/OMUFO/MTS/MTS.1.A1.READ can specify OM.SW+/OMUFO/MTS.1.A1.READ; Windows
downloads join that to the configured share root, defaulting to \\LON-ESDEV-02\OBSW.
The client does not derive share paths from API paths. Omit shareRelativePath for
API-only files; do not return null or an empty string. Relative paths accept either slash
style but reject absolute paths, drive prefixes, traversal, and unsafe Windows names.
Share contents are accepted only when their SHA-256 matches the API manifest.
Unavailable or mismatched share files, entries without shareRelativePath, and
non-Windows hosts use API downloads instead.
The share is only read; publishing always uses the API.
UniBasic detection, completions, definitions, linting, template actions, Open Item, and
server history use the original API identity for downloaded files. Definition targets
not downloaded locally still open through the virtual filesystem. Template actions
return edits to the local editor; they do not publish them.
Sync baselines and server bindings are persisted in VS Code extension storage, separately
from source files. Reopening a copy with the same extension profile and server settings
restores its mappings. Keep that metadata when moving between sessions; copying the
source folder alone does not register a new working copy. Different server settings have
separate bindings. A publish sends the saved bytes with the downloaded ETag; server
changes cause a conflict rather than an overwrite. To resolve a conflict, preserve your
local edits separately, remove the conflicting local file, refresh, then reapply your
edits against the current version and publish.
This first version publishes existing tracked files individually. New files, renames,
deletions, automatic background sync, and propagating remote deletions are not supported.
Files with unsafe Windows names fail explicitly rather than being renamed silently.
Local read-only metadata prevents publishing, but does not make the disk file read-only.
Open the local copy for editing rather than editing both virtual and local versions.
Server prerequisite: implement GET /dev/fs/manifest{path} and the ETag guarantees in
the OpenAPI contract. The new local mode requires this
endpoint; virtual mode does not. Manifest hashes and ETags must describe the same bytes,
and writes with expectedEtag must compare and write atomically. Do not let template
actions persist changes: they must only return transformed editor content.
Commands
Cygnum: LoginCygnum: ConfigureCygnum: Connect to CygnumCygnum: Refresh Remote FilesCygnum: Download or Refresh Local Working CopyCygnum: Publish Local FileCygnum: Open TerminalCygnum: Open ItemCygnum: Apply Template Action
Deep Links
You can open Cygnum items directly from external links using VS Code URI handling.
Format:
vscode://CACI-EnterpriseSystems.cygnum-dev-editor/open-item?recordId=<URL-ENCODED_RECORD_ID>
Copy/paste example:
vscode://CACI-EnterpriseSystems.cygnum-dev-editor/open-item?recordId=OUFO%20O.CODE.V
If you need to build a link manually, URL-encode the recordId value so spaces become %20.
Troubleshooting:
- If nothing opens, make sure the extension is installed and enabled in the VS Code instance handling the link.
- If you see
Unsupported link path, the path must be exactly /open-item.
- If you see
Deep link is missing required query parameter recordId, add ?recordId=... to the URL.
- If you see
Record ID cannot contain path separators, remove / and \\ from the record id.
- If the link opens VS Code but not the item, run
Cygnum: Login and then try again.
Remote API Notes
/dev/fs/stat is the source of file metadata used by the client.- Return canonical
path values for direct item routes so the client can reveal the real remote location in Explorer.
- Return
contentType: text/x-unibasic only for UniBasic files; all other files should return their normal content type or omit the field.
Configuration
The extension contributes these settings:
cygnum-dev-editor.authentication.providercygnum-dev-editor.authentication.tenantIdcygnum-dev-editor.authentication.clientIdAcygnum-dev-editor.authentication.clientIdBcygnum-dev-editor.api.hostnamecygnum-dev-editor.api.portcygnum-dev-editor.api.basePathcygnum-dev-editor.api.filePathcygnum-dev-editor.terminal.routecygnum-dev-editor.workspace.disableGitAutoRepositoryDetectionOnMountcygnum-dev-editor.localWorkingCopy.shareRoot (defaults to \\LON-ESDEV-02\OBSW)
